Migration Guide

How to move from the legacy integration (meta tags, Auth0 SPA, embed/encode lock modes) to the recommended setup (Capsule encryption, HttpOnly cookie auth, same-origin proxying).

Before and after

Aspect	Legacy	Recommended
Content metadata	<meta property="sesamy:price"> tags	resourceJWT inside the DCA manifest
Content protection	embed, encode, or proxy lock modes	Capsule (AES-256-GCM encryption)
Authentication	Auth0 SPA plugin (tokens in localStorage)	HttpOnly cookie auth via reverse proxy
API requests	Direct to api2.sesamy.com	Proxied through your domain (/sesamy-api)

Both systems can run side by side during the transition. sesamy-js reads metadata from the resourceJWT first and falls back to meta tags when no DCA manifest is present. Cookie auth and Auth0 can coexist on different pages.

Step 1: Set up the reverse proxy

Configure your CDN or server to proxy Sesamy requests. See proxy setup for detailed guides.

You need two rules:

Your path	Destination
/auth/*	https://api2.sesamy.com/auth/*
/sesamy-api/*	https://api2.sesamy.com/*

Verify: Open /auth/userinfo in your browser. You should see a JSON response (even if authenticated: false).

Step 2: Switch to HttpOnly cookie auth

Update your sesamy-js config to use the proxy and cookie auth:

Before

{
  "clientId": "your-vendor-id",
  "auth": {
    "domain": "login.yoursite.com"
  }
}

After

{
  "clientId": "your-vendor-id",
  "vendorId": "your-vendor-id",
  "api": { "endpoint": "/sesamy-api" },
  "auth": { "useHttpCookies": true }
}

What changes:

• The Auth0 SPA plugin is no longer loaded (sesamy-js uses the built-in cookie auth instead)
• Tokens are stored in HttpOnly cookies instead of localStorage
• All API and auth requests go through your proxy

What stays the same:

• The <sesamy-login> component works identically
• Existing readers with Auth0 sessions will need to log in again (their localStorage tokens are not migrated)

Verify: Log in on your site. Check DevTools > Application > Cookies and confirm you see at and sesamy_is_authenticated cookies on your domain.

Step 3: Enable Capsule encryption

Add Capsule to your sesamy-js config:

{
  "clientId": "your-vendor-id",
  "vendorId": "your-vendor-id",
  "api": { "endpoint": "/sesamy-api" },
  "auth": { "useHttpCookies": true },
  "capsule": { "enabled": true }
}

Then update your CMS or build pipeline to encrypt premium content using the Sesamy Capsule API. The output is a DCA manifest (<script class="dca-manifest">) and sealed content (<template class="dca-sealed-content">).

During the transition, you can have:

• New articles with Capsule encryption
• Old articles with <sesamy-content-container> and meta tags

sesamy-js handles both. Capsule pages are decrypted automatically; non-Capsule pages continue to use the lock mode on the content container.

Step 4: Remove legacy meta tags (optional)

Once all content is published with Capsule and the resourceJWT, you can remove the legacy meta tags:

<!-- These are no longer needed when using Capsule -->
<meta property="sesamy:price" content="29" />
<meta property="sesamy:currency" content="SEK" />
<meta property="sesamy:access-level" content="entitlement" />

The resourceJWT inside the DCA manifest carries all this information.

No rush

Meta tags continue to work as a fallback. You do not need to remove them from old articles -- sesamy-js simply ignores them when a DCA manifest is present.

Step 5: Remove Auth0 plugin script (optional)

If you were loading the Auth0 plugin via a script tag, you can remove it:

<!-- Remove this -->
<script src="https://cdn.sesamy.com/sesamy-js/latest/auth0-plugin.iife.js"></script>

The Scripts Host bundle automatically excludes the Auth0 plugin when useHttpCookies is enabled.

Rollback

If you need to roll back at any point:

1. Revert the sesamy-js config to the previous version (remove capsule, auth.useHttpCookies, and api.endpoint)
2. Re-add the Auth0 plugin script if you removed it
3. The meta tags on existing articles still work, so content access is unaffected

Next Steps

• CMS Integration Overview -- The complete recommended setup
• Authentication Options -- Detailed comparison of auth approaches
• Content Protection -- Capsule encryption reference