While Gatekeeper enables very sophisticated website configurations, the complexity mostly lies in Gatekeeper itself and secondarily, in the policies. The actual technical integration is meant to be fairly light.

Integration overview

Gatekeeper request/response cycle

After your team has finished the first six steps of the Getting started guide, what remains is having your webserver check Gatekeeper when deciding how to respond to incoming web requests.

For the most part, your webserver will be contacting Gatekeeper via the Visits authorization endpoint. When a visitor requests a URL, call Gatekeeper's authorization endpoint and pass along information about the visit: the visitor's IP address, the URL of the requested page, the user ID (if applicable), and the user_agent string. Gatekeeper will generally respond in one of three expected ways:

"allow"Show the user the requested web page.
"deny"Do not show the user the requested web page. Instead, show the user a different page, which might be a paywall or some other explanation. Note that there is an optional reason field that your team might want to display to the user.
"captcha"Do not show the user the requested web page. Instead, show the user a CAPTCHA challenge. When the user submits a solution, let Gatekeeper know whether the user successfully answered the challenge or not via the /gatekeeper/visits/:visit_id/captcha endpoint. Even if the user fails the challenge, be sure to let Gatekeeper know since some policies consider the number of CAPTCHA failures.

Your team might also want to use custom authorizations, in which case you'll also want to craft responses for each custom authorization.

Additional pointers

If your site has the concept of premium members or subscribers and membership in that set changes as people sign up or let subscriptions expire, you'll want to update Gatekeeper about the changes in membership via the Visitor Groups endpoint. For more information, see the tutorial on whitelisting.

If you want to show users how many free articles they have left, you can see how many visits a user has accumulated per policy using the /gatekeeper/visits/count/for-policy endpoint.