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

Keep existing readers logged in

By default, readers with an existing Auth0 SPA session are logged out after the switch — their localStorage tokens are not migrated. Add auth.migrateLegacySession: true to carry them over with a single silent login on first load:

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

It only carries over readers whose session still exists at the auth provider, and falls through to anonymous otherwise. See BFF authentication for details. Remove the flag once legacy sessions have aged out.

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