Zephr User Guide


109 views 0

You can use bypasses to offer your end users extra access without using the grant checks used in your rule. Each time your end user encounters a grant check in the rule, they are granted the relevant feature, product or trial whether you have added the grant to the user or not.

For example, if you have defined a rule with a feature check on an article to allow end users to view the content, any end users that meet the criteria defined for the bypass can view the content without you granting the product to that user.

You can define bypasses using trusted referrers or IP whitelisting. If using a trusted referrer, they can create trusted links as described in Create Trusted Links below.

To set up bypasses for end users, in the following ways:

  • Enable the Bypass extension, as described in Enable the Bypass Extension below. Use this, for example, if you want to allow anonymous users to access your content when they view it from a specific location – such as a cafe – or show a specific message to users in the defined IP range

    Note: To use the Bypass decision node to bypass the product check in a rule, you must use the Bypass extension. If you do not see the Bypass extension in the Extensions, or the Bypass decision node in the decision node bar, contact support to arrange access.

  • Configure bypasses, as described in Configure Bypasses below. Use this to allow any users in an IP range, or referred from a trusted referrer link, to bypass any product checks

Enable the Bypass Extension

To enable the Bypass extension, complete the following steps:

  1. Select the Settings icon from the main menu
  2. Select Extensions

    The Extensions screen displays.

  3. Scroll to the Internal section and select Bypass

    Note: If you do not see the Bypass option, contact support to request access.

    The Bypass screen displays, as illustrated below:

    Activate Bypass Extension

  4. Select the toggle to activate the Bypass extension on the sites that you require
  5. Select the Save button

When you build a rule, drag the Bypass decision point to the rules canvas. Connect the Yes node of the Bypass decision point to the outcome that allows access to the feature and the No node to the existing rule. This means that end users who do not meet the bypass criteria get the regular experience, for example being presented with a registration wall, as illustrated below:

Bypass Rule

Note: If you do not see the Bypass decision node, contact support to request access.

When a rule runs and the user is accessing the site from a whitelisted IP address or a trusted referrer, the checks are completed as follows:

  • All feature checks allow access to the feature
  • All product checks allow access to the product
  • All trials include the end user in the trial

Before any end users can meet the criteria, you must configure bypasses, as described in Configure Bypasses.

Configure Bypasses

To configure bypasses, complete the following steps:

  1. Select B2B from the main menu
  2. Select Bypasses from the options

    The Bypasses screen displays.

  3. Select the radio button from the Current Identifier Source options. The options are as follows:
    • Path
    • Content ID Parameter
  4. If you want to allow third-party sites to create links to pages proxied through Zephr that bypass product checks, select the Add a Trusted Referrer button

    The Add a Trusted Referrer dialog displays, as illustrated below:

    Trusted Referrers

    Complete the Add a Trusted Referrer dialog box as follows:

    1. Enter the domain of the third-party through which traffic is referred to Zephr in the Referrer Domain text box
    2. Note the secret key generated in the Secret field, which you must provide to the trusted referrer so that they can create trusted links. For further information on creating trusted links, see Create Trusted Links below
    3. Select the Add button to return to the Bypasses screen and create the trusted referrer. Selecting the Cancel button displays the Bypasses screen without creating a trusted referrer
  5. If you want to whitelist IP addresses, enter the IPv4 or IPv6 addresses or CIDR blocks to whitelist in the IP Whitelist checkbox

    Enter each address or block on a new line, as illustrated below:

    IP Whitelist

  6. Select the Save button

Create Trusted Links

A trusted link uses a btr token, using the btr= format, which must be generated server-side for each link by the referrer. The link only works when followed from a page on the referrer’s domain. A trusted link looks similar to the following:


Zephr uses the Referer HTTP header to validate the btr token. Zephr cannot validate the btr token if the link is copied and pasted, sent by email or published on a different site.

To generate btr tokens, your trusted referrer must use server-side code.

To obtain the btr token for a specific link, use MD5 to hash the path in the link with the secret generated in the Add a Trusted Referrer dialog box. The two parts are separated with a pipe (|) symbol.

The following examples show the code required for a trusted referrer with a website of trusted-forum.biz and a generated secret of 89b4c0e4-e95f-4981-b872-b85ea5aec0ff who want to generate a link to http://your-website.com/stories/article228.html.

Java Example

public String createBTRToken(String path, String secret) {
    try {
        return DatatypeConverter.printHexBinary(MessageDigest.getInstance("MD5").digest((path + "|" + secret).getBytes(StandardCharsets.UTF_8);
    } catch (Exception e) {
        return "";
String trustedLink = "https://www.your-website.com/stories/article228.html?btr=" + createBTRToken("/stories/article228.html", "89b4c0e4-e95f-4981-b872-b85ea5aec0ff");

PHP Example

<?php echo 'https://www.your-website.com/stories/article228.html?btr=' . md5('/stories/article228.html|89b4c0e4-e95f-4981-b872-b85ea5aec0ff') ?>

JavaScript Example

Note: This is the node.js code required server-side.

 // assumes md5 was installed with npm install md5

var md5 = require('md5');

var trustedLink = 'https://www.your-website.com?btr=' + md5('/stories/article228.html' + | + '89b4c0e4-e95f-4981-b872-b85ea5aec0ff');

The trusted referrer must use JavaScript client-side to generate trusted links, or users can potentially create their own trusted links and spoof the Referer HTTP header to access content.