How to Upload a Microsite

How to upload a microsite using the Webscale Control Panel or API

A microsite is used to display custom pages while your application is in maintenance mode. A microsite can also contain custom files that are used in Web Controls, such as a Captcha you can specify for the Challenge Web Control.

Upload a microsite using the Webscale Control Panel

Microsite selection page
1. Click Microsite on the left-hand menu.

2. On this page you see a preview of the existing microsite and can upload your own. To upload your microsite, drag the microsite file from your local computer into the box, or click the box and choose the file from your local computer.

3. When the upload is complete, the preview window shows the microsite you uploaded. This site will display whenever you place the app in maintenance mode.

Upload a custom captcha

This method can also be used to create a custom captcha if the upload also contains a captcha.html file. The captcha.html file must include the following 2 divs in the html:

<div id=”protection-mode-captcha-error”></div>
<div id=”protection-mode-captcha”></div>

Upload a microsite using the API

The API endpoint at https://api.webscale.com/v2/files can be used to upload files to the data plane. Users can specify a role for the uploaded file. For example, this API endpoint can be used to upload a list of WAF (Web Application Firewall) rules that will be used by the application’s WAF. To upload an entire microsite or multiple files, upload a file in the .tar.gz format. Note that some file names are reserved.

An example of the API command using curl is here:

$ curl -X POST -H "Authorization: Bearer <token>" https://api.webscale.com/v2/files --header "Content-Type: multipart/form-data" -F "file=@<path-to-file>;filename=<filename>" -F role=<role>

Replace <token> with your API Access Key, <path-to-file> with the local file path, <filename> with the filename you want to specify for the file, and <role> for the role the file will perform once uploaded. To upload a captcha, use captcha-microsite.

The API response will be a JSON object containing a file id, which is 12 random alphanumeric characters. Example:

{
  "file_id": "v81v421bzsu7b6as",
  "download_key": "n13z1p0tevllerorr9js62lzuy0tu1"
}

Upload a custom captcha

The filename of the file to upload for a custom captcha must be index.html. If uploading a tar.gz file, the index.html for the captcha page must be in the root and not inside any subdirectories.

An example of the API command using curl is here:

$ curl -X POST -H "Authorization: Bearer <token>" https://api.webscale.com/v2/files --header "Content-Type: multipart/form-data" -F "file=@<path-to-file>;filename=<filename>" -F role=captcha-microsite

In order for the file you upload to work as a captcha it must include the following 2 divs in the html:

<div id=”protection-mode-captcha-error”></div>
<div id=”protection-mode-captcha”></div>

Patch the application using the API

To ensure the file is used by the captcha in Shield Mode or the Challenge Web Control, you must patch the application using the API. The JSON body of the patch (via API) must be:

{
  "protection_microsite_file": "/v2/files/<file-id>",
}

You can also generate the full API command via the patch function on the API Reference page with the following steps:

  1. Click the Applications API header.
  2. Click Patch for applications/{id}.
  3. In the Model Schema box, scroll to locate "protection_microsite_file": "string",. Hint: use ctrl+For cmd+F to locate this quickly.
  4. Copy and paste "protection_microsite_file": "string", into the body field located under Parameters.
  5. Edit the command appropriately, replacing "string" with "/v2/files/<file-id>". The <file-id> must be replaced with the actual file id from the API response received when the file was uploaded.
  6. Enter the application’s id in the id parameter field.
  7. Copy the output from the Model Schema box. You can now use curl (or whatever method you usually use) to run this command and patch the application.

The patch function can also be used to customize other aspects of your application. Please refer to the API documentation for more information.

Further Reading

Have questions not answered here? Please Contact Support to get more help.


Last modified September 2, 2020