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.

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"}}'

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_TOKEN");
request.AddParameter("application/json", "{\"error_page\": {\"html\": \"\", \"show_log_link\":false, \"url\": \"http://www.example.com\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

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

}

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

var request = require("request");

var options = { method: 'PATCH',
  url: 'https://YOUR_DOMAIN/api/v2/tenants/settings',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Bearer YOUR_TOKEN' },
  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);
});

#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];

$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;
}

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

require 'uri'
require 'net/http'

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

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"
  ]]

let postData = NSJSONSerialization.dataWithJSONObject(parameters, options: nil, error: nil)

var request = NSMutableURLRequest(URL: NSURL(string: "https://YOUR_DOMAIN/api/v2/tenants/settings")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.HTTPBody = postData

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    println(error)
  } else {
    let httpResponse = response as? NSHTTPURLResponse
    println(httpResponse)
  }
})

dataTask.resume()

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

{client_id}
{connection}
{lang}
{error}
{error_description}
{tracking}
{logo_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>Hello {{name}}. This error was generated {{'\''now'\'' | date: '\''%Y %h'\''}}.<\h1>", "show_log_link": false, "url": ""}}'

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

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>Hello {{name}}. 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))

}

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>Hello {{name}}. This error was generated {{'now' | date: '%Y %h'}}.<\\h1>\", \"show_log_link\": false, \"url\": \"\"}}")
  .asString();

var request = require("request");

var options = { method: 'PATCH',
  url: 'https://login.auth0.com/api/v2/tenants/settings',
  headers: 
   { 'content-type': 'application/json',
     authorization: 'Bearer YOUR_TOKEN' },
  body: '{"error_page": {"html": "<h1>Hello {{name}}. This error was generated {{\'now\' | date: \'%Y %h\'}}.<\\h1>", "show_log_link": false, "url": ""}}' };

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

  console.log(body);
});

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_TOKEN",
                           @"content-type": @"application/json" };

NSData *postData = [[NSData alloc] initWithData:[@"{"error_page": {"html": "<h1>Hello {{name}}. This error was generated {{'now' | date: '%Y %h'}}.<\h1>", "show_log_link": false, "url": ""}}" dataUsingEncoding:NSUTF8StringEncoding]];

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];

$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>Hello {{name}}. 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;
}

import http.client

conn = http.client.HTTPSConnection("login.auth0.com")

payload = "{\"error_page\": {\"html\": \"<h1>Hello {{name}}. 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"))

require 'uri'
require 'net/http'

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>Hello {{name}}. This error was generated {{'now' | date: '%Y %h'}}.<\\h1>\", \"show_log_link\": false, \"url\": \"\"}}"

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

import Foundation

let headers = [
  "authorization": "Bearer YOUR_TOKEN",
  "content-type": "application/json"
]

let postData = NSData(data: "{"error_page": {"html": "<h1>Hello {{name}}. This error was generated {{'now' | date: '%Y %h'}}.<\h1>", "show_log_link": false, "url": ""}}".dataUsingEncoding(NSUTF8StringEncoding)!)

var request = NSMutableURLRequest(URL: NSURL(string: "https://login.auth0.com/api/v2/tenants/settings")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.HTTPBody = postData

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    println(error)
  } else {
    let httpResponse = response as? NSHTTPURLResponse
    println(httpResponse)
  }
})

dataTask.resume()

Docs

Custom Error Pages

How to customize the error page

Redirect users to a custom error page

Render a custom error page

Was this article helpful?