> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Learn how to create a custom error page for authorization error events.
# Customize Error Pages
export const AuthCodeGroup = ({children, dropdown}) => {
const [processedChildren, setProcessedChildren] = useState(children);
useEffect(() => {
let unsubscribe = null;
function init() {
unsubscribe = window.autorun(() => {
const processChildren = node => {
if (typeof node === "string") {
let processedNode = node;
for (const [key, value] of window.rootStore.variableStore.values.entries()) {
const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
processedNode = processedNode.replaceAll(new RegExp(escapedKey, "g"), value);
}
return processedNode;
} else if (Array.isArray(node)) {
return node.map(processChildren);
} else if (node && node.props && node.props.children) {
return {
...node,
props: {
...node.props,
children: processChildren(node.props.children)
}
};
}
return node;
};
setProcessedChildren(processChildren(children));
});
}
if (window.rootStore) {
init();
} else {
window.addEventListener("adu:storeReady", init);
}
return () => {
window.removeEventListener("adu:storeReady", init);
unsubscribe?.();
};
}, [children]);
return {processedChildren};
};
export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
const [displayText, setDisplayText] = useState(children);
const [copyText, setCopyText] = useState(children);
const wrapperRef = React.useRef(null);
useEffect(() => {
let unsubscribe = null;
function init() {
if (!window.autorun || !window.rootStore) {
return;
}
unsubscribe = window.autorun(() => {
let processedChildrenForDisplay = children;
let processedChildrenForCopy = children;
for (const [key, value] of window.rootStore.variableStore.values.entries()) {
const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
let displayValue = value;
if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") {
displayValue = value.substring(0, 3) + "*****MASKED*****";
}
processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue);
processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value);
}
setDisplayText(processedChildrenForDisplay);
setCopyText(processedChildrenForCopy);
});
}
if (window.rootStore) {
init();
} else {
window.addEventListener("adu:storeReady", init);
}
return () => {
window.removeEventListener("adu:storeReady", init);
unsubscribe?.();
};
}, [children]);
useEffect(() => {
if (!wrapperRef.current) return;
const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard);
let isOverriding = false;
const handleClick = e => {
const button = e.target.closest('[data-testid="copy-code-button"]');
if (!button || !wrapperRef.current.contains(button)) return;
isOverriding = true;
navigator.clipboard.writeText = text => {
if (isOverriding) {
isOverriding = false;
navigator.clipboard.writeText = originalWriteText;
return originalWriteText(copyText);
}
return originalWriteText(text);
};
setTimeout(() => {
if (isOverriding) {
isOverriding = false;
navigator.clipboard.writeText = originalWriteText;
}
}, 100);
};
const wrapper = wrapperRef.current;
wrapper.addEventListener('click', handleClick, true);
return () => {
wrapper.removeEventListener('click', handleClick, true);
if (navigator.clipboard.writeText !== originalWriteText) {
navigator.clipboard.writeText = originalWriteText;
}
};
}, [copyText]);
return
{displayText}
;
};
When an authorization error occurs, and your callback URL is valid, the Authorization Server 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.
| Parameter | Description |
| ------------------- | --------------------------------------------------------- |
| `client_id` | Identifier of the Auth0 application. |
| `connection` | Connection used at the time of error. |
| `lang` | Language set for use at the time of error. |
| `error` | Error code of the error. |
| `error_description` | Description of the error. |
| `tracking` | Identifier used by Auth0 to find errors in internal logs. |
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 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 `url` field in the JSON body to point to the location of the error page.
```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 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);
});
```
```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
```
| Value | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:tenant_settings`. |
| `show_log_link` | Indicates whether to show a link to the error in your tenant logs. Valid values are `true` and `false`. |
| `url` | Location of the custom error page to which you want to redirect. |
### Render a custom error page
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.
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}`
```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": "{{error | escape }} {{error_description | escape }} This error was generated {{'\''now'\'' | date: '\''%Y %h'\''}}.
", "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\": \"{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.
\", \"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 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\": \"{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.
\", \"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: '{{error | escape }} {{error_description | escape }} This error was generated {{\'now\' | date: \'%Y %h\'}}.
',
show_log_link: false,
url: ''
}
}
};
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://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\": \"{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.
\", \"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\": \"{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.
\", \"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\": \"{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.
\", \"show_log_link\": false, \"url\": \"\"}}"
response = http.request(request)
puts response.read_body
```
| Value | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:tenant_settings`. |
| `show_log_link` | Indicates whether to show a link to the error in your tenant logs. Valid values are `true` and `false`. |
| `html` | HTML of the custom error page you want to render. |
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)