Appearance

CMS Integrations ​

An overview of integrating Sesamy into your CMS, covering the recommended setup and the building blocks that platform-specific guides build upon.

The recommended integration uses three components working together:

  1. Capsule encryption for content protection -- content is AES-256-GCM encrypted on the page, cache-friendly, and secure at rest
  2. HttpOnly cookie auth via a reverse proxy -- tokens never touch JavaScript, eliminating XSS token theft
  3. Same-origin proxying of API and auth requests -- avoids third-party cookie issues with Safari ITP and keeps all traffic on your domain
html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Premium Article</title>

    <!-- Load Sesamy bundle (includes components + auth) -->
    <script type="module" src="https://scripts.sesamy.com/s/YOUR_VENDOR_ID/bundle/stable"></script>

    <!-- sesamy-js config: BFF auth + Capsule + proxy -->
    <script type="application/json" id="sesamy-js">
      {
        "clientId": "your-vendor-id",
        "vendorId": "your-vendor-id",
        "api": { "endpoint": "/sesamy-api" },
        "auth": { "useHttpCookies": true },
        "capsule": { "enabled": true }
      }
    </script>
  </head>
  <body>
    <header>
      <h1>My Publication</h1>
      <sesamy-login></sesamy-login>
    </header>

    <article
      publisher-content-id="article-2025-001"
      item-src="https://example.com/articles/premium-article"
    >
      <h1>Premium Article Title</h1>
      <p>This introduction is visible to everyone.</p>

      <!-- Paywall: shown when user lacks access -->
      <sesamy-paywall
        settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
      ></sesamy-paywall>

      <!-- Encrypted content: decrypted automatically by Capsule -->
      <script class="dca-manifest" type="application/json">
        { ... }
      </script>
      <template class="dca-sealed-content">
        <div data-dca-content-name="bodytext">...encrypted...</div>
      </template>
    </article>

    <sesamy-visibility>
      <div slot="logged-in">
        <a href="#" onclick="window.sesamy.profile.openHostedAccountPage()">My Account</a>
      </div>
    </sesamy-visibility>
  </body>
</html>

With this setup your CDN can hard-cache every page. sesamy-js detects the encrypted content, authenticates the user via cookies, fetches the decryption key, and injects the decrypted HTML -- all client-side.

How It Works ​

Content protection ​

Sesamy handles the locking and unlocking of articles. When a reader visits a premium page, Sesamy decides what to show based on their entitlements. This lets you use features like paywall strategies (serving different paywalls to different readers) and leaky paywall (granting free access to a set number of articles).

With Capsule, the premium content is encrypted at publish time. The resourceJWT inside the DCA manifest carries all content metadata (price, currency, content ID, pass) so you do not need separate meta tags. sesamy-js reads this token automatically.

Capsule is recommended but not required

Other content protection strategies (proxy, encode, embed, event) remain available. They are useful for specific use cases, but Capsule provides the best combination of security and cacheability.

Authentication ​

The recommended approach is to proxy auth requests through your own domain (e.g. /sesamy-auth) so cookies are first-party. This eliminates third-party cookie restrictions in Safari and other browsers. See authentication options for alternatives including custom subdomains and OIDC.

API proxying ​

By proxying API requests through a subpath like /sesamy-api, all traffic stays on a single origin. This is important because Apple increasingly restricts requests served from different IP addresses. Cloudflare, Bunny CDN, and similar platforms make this straightforward. See proxy setup for CDN-specific guides.

Web Components ​

Sesamy provides web components that handle authentication, paywall display, and content gating. They work with any HTML page or framework.

Loading the components ​

The simplest way is via the Scripts Host, which bundles sesamy-js, the auth plugin, and the web components:

html
<script type="module" src="https://scripts.sesamy.com/s/YOUR_VENDOR_ID/bundle/stable"></script>

sesamy-login ​

Renders a login/logout button with user avatar. Handles the full auth flow automatically.

html
<sesamy-login></sesamy-login>

See sesamy-login reference for all properties, events, and slots.

sesamy-paywall ​

Displays pricing options and purchase/subscribe buttons. Fetches its configuration from a settings-url endpoint managed via the Sesamy dashboard.

html
<sesamy-paywall
  settings-url="https://api2.sesamy.com/paywalls/YOUR_VENDOR_ID/YOUR_PAYWALL_ID"
></sesamy-paywall>

Paywall without content lock

You can use <sesamy-paywall> on its own for subscription pages or donation pages -- it does not require a <sesamy-content-container>.

See sesamy-paywall reference for all properties, events, and slots.

sesamy-content-container ​

Manages content visibility based on the user's entitlements. Pair it with a <sesamy-paywall> for the full experience.

html
<sesamy-content-container lock-mode="proxy">
  <div slot="preview">
    <p>This preview is visible to everyone...</p>
  </div>
</sesamy-content-container>

See sesamy-content-container reference for the full API.

sesamy-visibility ​

Shows or hides content based on authentication status. No entitlement check -- just logged in or not.

html
<sesamy-visibility>
  <div slot="logged-in"><p>Welcome back!</p></div>
  <div slot="not-logged-in"><p>Log in to access your subscriptions.</p></div>
</sesamy-visibility>

How components find configuration ​

Components traverse the DOM upward to find configuration attributes. Set shared properties on a parent element (typically an <article> tag) and all child components inherit them:

html
<article
  publisher-content-id="article-123"
  item-src="https://example.com/articles/premium-article"
  price="4.99"
  currency="EUR"
>
  <sesamy-paywall settings-url="..."></sesamy-paywall>
  <sesamy-content-container lock-mode="proxy">
    <div slot="preview">Preview...</div>
  </sesamy-content-container>
</article>

Next Steps ​

Released under the MIT License.

Copyright © 2025 Sesamy AB