Linking sites with a cross-site pass
A cross-site pass lets readers sign in and pay on one site, the issuer, and read gated posts on sibling sites under the same parent domain, the checkers, which keep no accounts of their own. One account and one subscription then open every site in the group.
Use it when one site sells (a shop or subscribe site, say shop.example.com) and one or more content sites (example.com) gate their posts but should not run checkouts and reader accounts of their own. Every site must be served over HTTPS and share a parent domain, because the pass is a secure cookie set on that domain. One issuer can serve several checkers.
How a reader experiences it
The issuer sets a signed cookie, the pass, on the parent domain when a reader signs in, and again on any front-end page they view there once their pass is missing or stale. A checker reads it on a gated post and opens what it carries:
- Subscriptions, as the date ranges the reader’s subscriptions cover. The checker judges each post against those ranges with its own access model and content dates (below).
- Posts and terms bought for that checker, by the checker’s own post and term IDs.
A pass also counts as an account on the checker: it gets a reader past a registration wall, and on a metered post the checker asks the issuer to count one of that reader’s free reads (Outages and free reads).
The pass is a short-lived copy of the issuer’s answer. Once it is five minutes old the checker asks the issuer for a fresh one, server to server, so a cancelled subscription stops working within minutes. While the issuer cannot be reached, a checker honours a pass for up to a day from when it was issued. Signing out on the issuer, logging out everywhere or changing the password ends the sign-in session the pass was issued under, so it can no longer be renewed on any device. A “remember me” sign-in gets a pass the browser keeps as long as the sign-in; any other sign-in gets one the browser drops when it closes. Readers sign in on the issuer, so its fabrica_monetization_kit_remember_sign_in decides which they get; by default no sign-in is remembered (see Walls and access).
What a pass does not carry, so a checker never honours it:
- author purchases, and author or term subscriptions;
- purchases limited to a range of content dates;
- access the issuer grants through
fabrica_monetization_kit_user_has_access; - purchases of the issuer’s own content, since no checker shares its IDs.
A pass opens only the post a singular page is showing, never posts in a list, an excerpt or a feed, whose output is shared between readers. A gated page shown to a reader carrying a pass is kept out of shared caches.
Setting it up
Set it up in each site’s wp-config.php, not in the database, where every administrator could read the issuer’s secret key and every copy of the database would carry it to staging:
| Constant | Issuer | Checker |
|---|---|---|
FABRICA_MONETIZATION_KIT_PASS_ROLE |
'issuer' |
'checker' |
FABRICA_MONETIZATION_KIT_PASS_SECRET_KEY |
the base64 Ed25519 secret key | — |
FABRICA_MONETIZATION_KIT_PASS_PUBLIC_KEY |
— (derived from the secret key) | the matching public key |
FABRICA_MONETIZATION_KIT_PASS_RECHECK_SECRET |
a random string of at least 32 characters | the same string |
FABRICA_MONETIZATION_KIT_PASS_COOKIE_DOMAIN |
the parent domain, leading dot included | the same |
FABRICA_MONETIZATION_KIT_PASS_ISSUER_URL |
— | the issuer’s home URL, https:// |
FABRICA_MONETIZATION_KIT_PASS_SITES |
the content sites it sells for, as an array of alias => home URL, https:// |
— |
FABRICA_MONETIZATION_KIT_PASS_SITE |
— | this site’s alias in the issuer’s SITES |
// On the issuer, shop.example.com
define('FABRICA_MONETIZATION_KIT_PASS_ROLE', 'issuer');
define('FABRICA_MONETIZATION_KIT_PASS_SECRET_KEY', '…');
define('FABRICA_MONETIZATION_KIT_PASS_RECHECK_SECRET', '…');
define('FABRICA_MONETIZATION_KIT_PASS_COOKIE_DOMAIN', '.example.com');
define('FABRICA_MONETIZATION_KIT_PASS_SITES', ['news' => 'https://example.com']);
// On the checker, example.com
define('FABRICA_MONETIZATION_KIT_PASS_ROLE', 'checker');
define('FABRICA_MONETIZATION_KIT_PASS_PUBLIC_KEY', '…');
define('FABRICA_MONETIZATION_KIT_PASS_RECHECK_SECRET', '…');
define('FABRICA_MONETIZATION_KIT_PASS_COOKIE_DOMAIN', '.example.com');
define('FABRICA_MONETIZATION_KIT_PASS_ISSUER_URL', 'https://shop.example.com');
define('FABRICA_MONETIZATION_KIT_PASS_SITE', 'news');
Make a key pair once per environment with \Fabrica\MonetizationKit\Pass\Token::generateKeyPair(), which returns the public and secret halves, base64-encoded. With WP-CLI on the issuer: wp eval 'print_r(\Fabrica\MonetizationKit\Pass\Token::generateKeyPair());'. A fresh pair per environment means a database copied to staging can never carry production’s. The secret key goes on the issuer only; the public key goes on every checker.
The recheck secret is how the issuer knows a renewal, a free-read count or a settings request really comes from one of its checkers. Any random string of 32 characters or more will do, the same on every site in the group.
SITES is the issuer’s list of the content sites it serves. An alias is lowercase letters, digits and hyphens, a letter first. The issuer accepts checkout and sign-in requests from a browser only on those sites’ pages, and sends readers back only to those hosts. A purchase of a checker’s content is recorded on the issuer under that checker’s alias and its own post or term ID, and the pass carries it there. A checker without SITE honours subscriptions but no purchases, and its wall cannot sign readers in where they are.
A configuration is refused when, on the issuer, the secret key is not a valid key, or, on a checker, the public key is not a valid key or the issuer URL does not start with https://. On either, it is refused when the recheck secret is shorter than 32 characters, the cookie domain is empty, an alias is malformed or a SITES URL does not start with https://. What a refusal leaves working is in What the role decides.
What the role decides
The role decides who keeps accounts and takes payment, before anything else:
- Issuer — signs readers up and in and takes payment, as any selling site does, whatever
fabrica_monetization_kit_restriction_onlysays. Stripe and its other settings still apply. - Checker — never does, whatever that filter or its own Stripe keys say. Its sign-up, sign-in, payment, subscription, campaign and Stripe webhook routes answer 404, as on a restriction-only site, and it registers none of the Account, Contributions, Membership or Signup blocks. Its walls sign readers in and take payment on the issuer (Selling from the checker’s wall). While the issuer cannot be reached, nothing here takes its place.
- Anything else — refused, and the site keeps no accounts and takes no payment until it is fixed.
- No role — the site stands alone, and keeps accounts and takes payment unless
fabrica_monetization_kit_restriction_onlyturns that off (Gating without selling).
The role is read as declared, never guessed from which keys are set. A checker whose keys are missing or wrong honours no pass, so readers meet the wall, and it still takes no payment and signs no one in. An issuer whose secret key is wrong goes on selling but issues no passes, so its content sites honour none. Either way every administrator sees a notice on every admin screen naming the constant at fault and what it leaves off.
What each role changes in the settings
On an issuer
Nothing is hidden: the issuer’s settings screen is a selling site’s, and every setting on it applies as usual. Several of them also set how every checker’s wall sells and signs readers in, because the issuer sends them to its checkers, which keep a copy for up to ten minutes. A change here reaches the checkers’ walls within that time:
- Gateways: the Stripe account and keys, the currency, whether Stripe Link and UK Direct Debit are offered, and whether Stripe waits for cookie consent.
- Monetization → Paywall → Subscriptions: the site-wide subscriptions a checker’s wall offers. They are also the subscriptions that count towards a pass, with any added through
fabrica_monetization_kit_access_product_ids. - Earlier posts covered (days) and Allow subscriptions from older content, which decide how far back a new subscription reaches on a checker’s date-based posts.
- Free reads per month: the monthly allowance a pass holder’s reads on every checker count against, along with their reads on the issuer.
- Accounts & login → Login method, and the registration wall’s Collect reader’s name, which a checker’s sign-in and registration forms follow.
- The sign-in page a checker’s wall links to: WooCommerce’s My Account page where WooCommerce is active, else the account page, else
wp-login.php.
fabrica_monetization_kit_restriction_only has no effect on an issuer.
On a checker
The checker hides what it would ignore, and says so once. A notice under the tabs, on every tab, links to the issuer’s settings and says payments, sign-in, subscriptions, memberships, donations, Gift Aid, author access and the free-read allowance are set there. The status strip above the Monetization panels shows only the Paywall’s status, since the panels below it are hidden.
Hidden, because the issuer’s version applies:
- the Gateways and Accounts & login tabs. Opening either by URL shows only the notice. The checker’s own Stripe keys are never used and it needs no Stripe webhook, since the route is not registered. Its checkout waits for cookie consent when the issuer’s Wait for cookie consent before loading Stripe is ticked, not by a setting of its own; where the WP Consent API is active on the checker, the consent category it waits for is still the checker’s (
fabrica_monetization_kit_stripe_consent_category), and the checker lists Stripe’s cookies under that category for its consent banner. - on Monetization: the Memberships, Contributions and Gift Aid panels; in the Subscriptions card, the site-wide, term and author subscriptions; Free reads per month; Collect reader’s name; Earlier posts covered (days); Allow subscriptions from older content; and author purchases under One-off purchases.
- the author price fields on user profiles and guest authors.
Hidden fields stay in the form and keep whatever value was saved, so switching a site back to standalone brings them back unchanged. While it is a checker, none of them affects what readers see. Its Campaigns menu and its Gift Aid claims export are not there at all.
Shown, and this site’s own, because the checker reads them itself:
- What gets gated, the default access level and Taxonomy priority.
- At the wall: hard or soft, and how long a closed wall stays closed. Soft for signed-in readers is offered once the pass configuration checks out, since a pass is how a reader counts as signed in here.
- Show reads remaining on metered posts.
- Registration wall: its heading, its intro and Offer what readers can buy, too. The wall itself only shows its form while the issuer lets this site register readers (Signing in and registering from the checker’s wall).
- Sellable taxonomies. A term bought for this site unlocks posts here only while its taxonomy is still sellable here, so taking a taxonomy off this list stops earlier purchases of its terms from opening anything.
- Access dates for subscriptions: the access model, the date meta key and the date taxonomy. They judge whether the date ranges a pass carries cover a post. Universal opens every post to an active subscription; date-based opens posts whose date falls inside a range. The tiered, category-based model opens nothing from a pass, which carries no tiers.
- One-off purchases of content and terms: which can be bought, how long access lasts, and the default, per-type and per-taxonomy prices. Per-post and per-term prices, and per-term access lengths, are set on the post and term as on any site.
- Advanced: Display, User-agent bypass patterns and Delete all data on uninstall. On a WooCommerce site, Mirror Stripe payments as WooCommerce orders has nothing to mirror, since no payment is taken here.
Where a checker’s wall gets what it sells:
- Subscriptions are the issuer’s site-wide subscriptions, at the issuer’s prices, billed on the issuer.
- Posts and terms are the checker’s own, at the checker’s prices. The price fields are read in the issuer’s currency, and while the issuer is answering the screen names that currency. When the issuer is down, or the checker’s configuration is refused, the screen cannot learn it and names this site’s own currency instead.
- Authors are never sold from a checker, since the pass cannot carry an author purchase back.
fabrica_monetization_kit_restriction_only has no effect on a checker. A checker whose configuration is refused still hides the same settings and still links its notice to the issuer URL it declares.
On a site with any other role
The settings screen is a standalone site’s, with nothing hidden, but the site keeps no accounts and takes no payment, so its payment and sign-in settings do nothing until the role is fixed.
The Cross-site pass panel
The Advanced tab ends with a read-only Cross-site pass panel showing the configuration in effect, one row per constant that is set, each with its constant’s name. The secret key and the recheck secret are shown only as set or not set, never their values; on an issuer the public key derived from the secret key is shown in full. A refused configuration gets a line naming the constant at fault, and its public key is then shown only as set or not set too, in case a secret was pasted into the wrong constant. With no role declared, the panel says the site stands alone. Nothing in it can be edited.
Selling from the checker’s wall
A pass checker’s wall sells while the issuing site can take payment. The checkout runs in the checker’s page but pays on the issuing site, which keeps the reader’s account, order and purchase. So the issuing site sets everything about money and accounts, as listed above, and the checker sets what it sells one at a time and at what price.
When a reader pays, the issuing site asks the checker, server to server, what that post or term sells for, and charges exactly that. The checker answers at POST /wp-json/fabrica-monetization-kit/v1/pass/offer with the amount, a term’s taxonomy, the title and the access length, and refuses anything its wall would not sell one at a time: a post while posts are not sold individually, an unpublished post, a post free or free with an account, a term made free or registration-only, a term on no published post or one your fabrica_monetization_kit_purchase_options filter removes, a taxonomy not sold one at a time or not publicly viewable, and anything priced at nothing. The answer is public, as the wall already shows it. If the checker refuses, cannot be reached within five seconds or gives no usable answer, no payment is taken. The title in the answer names the purchase on Stripe, on the order and on the reader’s account page.
The offer route arrived in 1.5.106. When upgrading a pair from an earlier version, update the issuing site first and the checker immediately after: until the checker answers the route, every purchase of its content is refused, whereas a checker updated first would show its own prices while the issuing site still charged its old ones.
The issuing site can keep the checkout off a content site’s pages, with a filter in its theme answered per content site by its alias (or an empty string for a checker that names none). On by default:
add_filter('fabrica_monetization_kit_pass_embedded_checkout', fn($on, $site) => $site === 'news' ? false : $on, 10, 2);
Off, that site’s walls mount no payment form and load no Stripe.js. They show the Subscribe link to the issuing site’s subscriptions page instead (fabrica_monetization_kit_pass_subscriptions_url, the issuing site’s front page by default), with nothing chosen in advance, and the reader buys there. The account, order and access are the issuing site’s either way.
Signing in and registering from the checker’s wall
By default a pass checker’s wall has no sign-in form: a reader signs in on the issuing site and comes back. The issuing site can let a checker’s wall sign readers in where they are, and register new ones, with two filters in the issuing site’s theme. Both are off by default and answered per content site, by its alias in FABRICA_MONETIZATION_KIT_PASS_SITES:
add_filter('fabrica_monetization_kit_pass_sign_in', fn($on, $site) => $site === 'news', 10, 2);
add_filter('fabrica_monetization_kit_pass_registration', fn($on, $site) => $site === 'news', 10, 2);
Registration needs sign-in on as well. With sign-in on, the checker’s paywall carries the usual sign-in form; with registration on too, a registration or metered post shows the registration wall to a reader without a pass, as on the issuing site. Either way the forms are the ones the issuing site would show — its login method, its code length and whether it asks for a name — because they run on the issuing site’s own login and register routes: the account lives there, and a new one fires fabrica_monetization_kit_regwall_registered there, with the content site’s alias as site in its context (post_id is then the content site’s post). Once the reader is signed in, the pass is set on the shared parent domain and the post is revealed in place, its reads-left line included.
The issuing site opens each login route to that content site’s pages only while its filter is on, and refuses it to every other origin. Its replies to the content site never carry WordPress’s own REST nonce. A password typed into the content site’s page can be read by every script that page runs, so keep the scripts on its walled pages to ones you trust; under an email-code login method the form leads with the code. A page served from a cache, rendered for an anonymous reader, offers a reader who signed in from a wall before in this browser to Continue as their email, after asking the issuing site whether they still are; if a reveal is refused there, the page reloads at a fresh URL rather than from the cache.
Known limit: without JavaScript. The sign-in form’s fallback posts the password to the issuing site’s wp-login.php, which sends the reader back to the article only because the plugin adds every pass site’s host to the issuing site’s allowed_redirect_hosts; a plugin that narrows that list strands them on the issuing site. A wrong password leaves them on the issuing site’s login page, not the article. Core’s cookie check there does not apply: the form sends no testcookie field.
Every route of the plugin’s that changes something answers only a real POST: a GET turned into one by ?_method= or X-HTTP-Method-Override, or a request asking for _jsonp, is refused with 403 fmk_not_post before any rate limit is spent. Another website can make a visitor’s browser send a GET — a link, a redirect, an image — with their cookies and no Origin, so without this it could sign them in to the attacker’s account or send codes to any address.
Outages and free reads
On a checker, the pass stands in for an account. A reader carrying one passes a registration wall. On a metered post, the checker asks the issuing site to count one of that reader’s free reads, against the issuing site’s own monthly allowance, and shows the post if it agrees. Reading the same post again that month costs nothing.
The checker waits up to three seconds for each answer from the issuing site. A failed answer pauses its asking for one minute; no answer at all, such as a timeout or a refused connection, pauses it for fifteen seconds. Both are written to the error log, at most once a minute. A misconfigured pair shows at once rather than a day later: when the issuing site answers that the recheck secret is wrong, or has no pass route at the issuer URL, the checker clears the reader’s pass instead of honouring it.
While the issuing site cannot be reached, every wall gives way to a short notice that subscriptions cannot be checked, because each of the wall’s links leads to the site that is down, and the wall sells nothing. The notice checks again by itself when the pause ends, and has a Try again button that checks at once. Both ask the checker’s reveal route with a POST, which reaches WordPress even if a cache served the page. A reader who may now read the post gets it in place. While the issuing site is still down, the notice waits for the next pause to end, and a reader who pressed the button is told so. Once it answers again, the page reloads to show the wall that applies now.
Some readers read on through the outage. A reader whose pass already covers the post, by subscription or purchase, never needs the issuing site. A reader whose wall would be soft anyway gets the post in full, with no wall and no notice, since closing the wall would let them read on: anyone on a post soft for everyone, and a pass holder on a post soft for signed-in readers. Everyone whose wall would be hard keeps it, as the notice — a reader without a pass on a post soft for signed-in readers, and every reader on a hard post. A wall that fabrica_monetization_kit_reader_wall_mode softens for a reader who is not signed in counts as hard here, because that reader could never close it. On a news site at metered, soft for signed-in readers, that means pass holders keep reading and visitors meet the notice.
Change the notice with the wall.issuer_unreachable text key, and the button with wall.issuer_unreachable.retry.