Skip to main content




Bypasses in Zephr allow you to offer extra access to users without the need for them to have the entitlement used within your decision or access rule.

It does this by allowing your user to bypass the entitlement check being used within your rule. In this instance, every entitlement check made for the user will return true, regardless of that user’s entitlement model. For example, if you have a rule requiring a user to have an Article entitlement in order to view content, users meeting the criteria of one of the bypasses will be able to view content that requires the Article entitlement for access, regardless of not having the entitlement granted.

It’s worth noting, Zephr Bypasses do not bypass the requirement for a user to be logged in. For example, if your rule firsts checks to see if a user is logged in, and the user with a bypass is not, then they will need to login before getting access to the content.

Bypasses can take a few forms within Zephr, including being used through Gifts, Trusted Referrers, and IP Whitelists. Click through for more detail on each of the Bypass options:

  • Gifts
  • Trusted Referrer
  • IP Whitelist


Zephr allows your to grant single access links for users, using the Gifts functionality. Using Gifts generates a link which grants users a single use access to a specific URL, regardless of their entitlements.

Configuring your Gift URL

To use the Gift functionality within Zephr you will need to have your Gift URL configured. This is the base URL that is used within the Gift link, and will often be your core website URL.

To set this up, navigate to Settings > CDN and find the Gifts heading under Configuration. Enter the base URL for gift links, then click Save.

Shows setting for configuring the gift base URL within the Admin Console

Adding a Gift

  • Navigate to Entitlement Manger > Gifts
  • Click Add Gift
  • In the modal that pops up, paste the slug of the page that you wish to grant access to.

  • Click Create Gift.

This will generate a link, which can be sent to a user for single use access to the page assigned to the gift.

Once created, a list of unclaimed gifts will be available under Entitlement Manager > Gifts. You can remove these by clicking Delete next to the relevant Gift.

Trusted Referrers

Zephr provides the ability for 3rd party sites – Trusted Referrers – to create links to zephr-proxied pages that bypass any entitlement checks (specified in request or feature rules) and grant full access to that page for that session.

A trusted link looks like this:

This is a regular link with the addition of a btr=<some token> query parameter- this parameter (or btr token) must be generated for each link, server-side, by the referrer. Each such link will work only when clicked from a page on that referrer’s domain, this works because Zephr uses the Referer HTTP header to validate the btr token: if the link is copy-pasted, sent via email, or published on another site, the Referer HTTP header will be either unset or something different, and so Zephr will not be able to validate the btr token.

Creating a Trusted Referrer within Zephr

To begin setting up your Trusted Referrers, navigate to Entitlement Manager > Bypasses > Trusted Referrers within the Zephr Admin Console.

Under Configuration > Content Identifier Source choose between Path and Content Id Parameter and click Save.

Following this, you will need to create a secret for the Trusted Referrer you are setting up. For a 3rd party to create a trusted link into a Zephr-proxied site, they will need to be given this secret. Under the Trusted Referrers heading, click Add Trusted Referrer. Set the Referrer Domain for the 3rd party you with to use as a Trusted Referrer. This should be the domain through which traffic will be referred to Zephr. Take note of the Secret, then click Create Trusted Referrer.

Instructing a Trusted Referrer how to create Trusted Links

The Trusted Referrer will need to use server-side code to generate btr tokens in order to create trusted links to your site.

The btr token for a particular link is obtained by using MD5 to hash the path part of the link together with the Trusted Referrer’s Secret (set up above), separated by a pipe ‘|’ symbol. Fortunately this is trivial in most server-side languages.

For example, for the website – which has been given Secret 89b4c0e4-e95f-4981-b872-b85ea5aec0ff -the following code snippets will all generate a valid link to


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 = "" + createBTRToken("/stories/article228.html", "89b4c0e4-e95f-4981-b872-b85ea5aec0ff");


<?php echo '' . md5('/stories/article228.html|89b4c0e4-e95f-4981-b872-b85ea5aec0ff') ?>

Javascript (node.js server-side)

// assumes md5 was installed with npm install md5

var md5 = require('md5');

var trustedLink = '' + md5('/stories/article228.html' + | + '89b4c0e4-e95f-4981-b872-b85ea5aec0ff');

NOTE: It is important that the Trusted Referrer uses client-side javascript to generate Trusted Links – otherwise it will be possible for tech-savvy users to create their own trusted links and spoof the Referer header to gain free access to any content.

IP Whitelist

The Zephr  IP Whitelist feature allows you to set a series of IP addresses to bypass the Entitlement checks that take place within your Rules.

This means users coming to your site from the IP addresses you have listed will not require any of the Entitlements checked for within your Zephr Rules. This is helpful for granting access to users on scale – for example, providing free access to your content for guests using your company wifi, or staff within your company offices.

The IP Whitelist can be set up by navigating to Entitlement Manager > Bypasses > IP Whitelist. Simply add the IP Addresses to the Edit IP Whitelist field as a newline delimited list (a new line for each IP) and click Save.

Zephr accepts IPv4 and IPv6 addresses or CIDR blocks.