Custom Error Pages

In the event of an authorization error, you may choose to display to your users either the default Auth0 error page or a customized error page.

This article will show you how to use a customized error page. For details on the default Auth0 error page see Error Pages.

If you choose to display a custom error page, you have two options:

Redirect the user to a custom error page
Configure Auth0 to render a custom error page on your behalf. This feature is only available via the Management API.

You can configure Auth0 to redirect users to a custom error page, using the Dashboard or the Management API.

If you use the Dashboard, follow these steps:

Log in to the Dashboard.
Click on your tenant name in the top right corner to bring up the associated dropdown box.
Select Settings to open the Tenant Settings page.
Scroll down to the Error Pages section.
Select the option Redirect users to your own error page.
Provide the URL of the error page you would like your users to see.

Instead of using the Management Portal, you may configure your error pages by making the appropriate PATCH /api/v2/tenants/settings call to the Management API.

To redirect users to a custom error page, update the url field of your JSON body to point to the location of the error page.

Error Page Redirect Option

If you use the API instead, use the PATCH /api/v2/tenants/settings endpoint. Update the url field of your JSON body to point to the location of the error page.

cURL
C#
Go
Java
Node.JS
Obj-C
...
- PHP
- Python
- Ruby
- Swift

curl --request PATCH \
  --url 'https://YOUR_DOMAIN/api/v2/tenants/settings' \
  --header 'authorization: Bearer YOUR_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}'

Was this helpful?/

var client = new RestClient("https://YOUR_DOMAIN/api/v2/tenants/settings");
var request = new RestRequest(Method.PATCH);
request.AddHeader("authorization", "Bearer YOUR_TOKEN");
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);

Was this helpful?/

package main

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

func main() {

	url := "https://YOUR_DOMAIN/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 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))

}

Was this helpful?/

HttpResponse<String> response = Unirest.patch("https://YOUR_DOMAIN/api/v2/tenants/settings")
  .header("authorization", "Bearer YOUR_TOKEN")
  .header("content-type", "application/json")
  .body("{\"error_page\": {\"html\": \"\", \"show_log_link\":false, \"url\": \"http://www.example.com\"}}")
  .asString();

Was this helpful?/

var request = require("request");

var options = {
  method: 'PATCH',
  url: 'https://YOUR_DOMAIN/api/v2/tenants/settings',
  headers: {authorization: 'Bearer YOUR_TOKEN', 'content-type': 'application/json'},
  body: {error_page: {html: '', show_log_link: false, url: 'http://www.example.com'}},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Was this helpful?/

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_TOKEN",
                           @"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://YOUR_DOMAIN/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];

Was this helpful?/

$curl = curl_init();

curl_setopt_array($curl, array(
  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 => "{\"error_page\": {\"html\": \"\", \"show_log_link\":false, \"url\": \"http://www.example.com\"}}",
  CURLOPT_HTTPHEADER => array(
    "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;
}

Was this helpful?/

import http.client

conn = http.client.HTTPSConnection("")

payload = "{\"error_page\": {\"html\": \"\", \"show_log_link\":false, \"url\": \"http://www.example.com\"}}"

headers = {
    'authorization': "Bearer YOUR_TOKEN",
    'content-type': "application/json"
    }

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

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

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

Was this helpful?/

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["authorization"] = 'Bearer YOUR_TOKEN'
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

Was this helpful?/

import Foundation

let headers = [
  "authorization": "Bearer YOUR_TOKEN",
  "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://YOUR_DOMAIN/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()

Was this helpful?/

The following parameters are appended to the url as query string to include the error information. Note that the parameters presented in the url vary depending on the error type.

client_id
connection
lang
error
error_description
tracking

You can render your custom error page with Liquid syntax using the following variables:

{client_id}
{connection}
{lang}
{error}
{error_description}
{tracking}
{log_url}

To provide the appropriate HTML, pass in a string containing the appropriate Liquid syntax to the html element:

cURL
C#
Go
Java
Node.JS
Obj-C
...
- PHP
- Python
- Ruby
- Swift

curl --request PATCH \
  --url https://login.auth0.com/api/v2/tenants/settings \
  --header 'authorization: Bearer YOUR_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": ""}}'

Was this helpful?/

var client = new RestClient("https://login.auth0.com/api/v2/tenants/settings");
var request = new RestRequest(Method.PATCH);
request.AddHeader("authorization", "Bearer YOUR_TOKEN");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"error_page\": {\"html\": \"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>\", \"show_log_link\": false, \"url\": \"\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Was this helpful?/

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

}

Was this helpful?/

HttpResponse<String> response = Unirest.patch("https://login.auth0.com/api/v2/tenants/settings")
  .header("authorization", "Bearer YOUR_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();

Was this helpful?/

var request = require("request");

var options = {
  method: 'PATCH',
  url: 'https://login.auth0.com/api/v2/tenants/settings',
  headers: {authorization: 'Bearer YOUR_TOKEN', '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: ''
    }
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Was this helpful?/

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_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];

Was this helpful?/

$curl = curl_init();

curl_setopt_array($curl, array(
  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 => array(
    "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;
}

Was this helpful?/

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

Was this helpful?/

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

Was this helpful?/

import Foundation

let headers = [
  "authorization": "Bearer YOUR_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()

Was this helpful?/

Docs

Custom Error Pages

Custom Error Pages

How to customize the error page

Redirect users to a custom error page

Customize error pages via the Management API

Redirect users to a custom error page

Render a custom error page

Was this article helpful?