Using JWT Authentication in MediaOS

JWT (JSON Web Token) allows you to securely pass user data into MediaOS, enabling seamless login experiences, automatic group enrollment, and instant newsletter or forum access. Whether you're building a custom paywall, CMS integration, or partner portal, JWT makes it possible to provision users in real time—without friction or redundant fields.

Why Use JWT? #

JWT integration allows external platforms (like a CMS, paywall, or custom login system) to pass authenticated user data into MediaOS. This eliminates redundant form fields, enables instant access to protected resources, and improves the user’s onboarding experience.

MediaOS accepts JWT payloads for secure, one-time user provisioning. This is ideal for single sign-on (SSO), paywall access, newsletter registration, or forum permissions.

Note: Never share your JWT secret publicly. Keep it secure, as it grants authorization to inject users into your MediaOS instance.

Where to Find Your JWT Secret #

Each website in MediaOS has a unique JWT secret. To locate yours, go to the Websites section within MediaOS and click Manage next to the website where you plan to use JWT. Within the settings panel, look for the field labeled JWT Secret.

If the field is blank or missing, you’ll need to reach out to your MediaOS administrator or support team to enable JWT for your environment.

Tip: If you don’t see a JWT secret or the field is empty, contact your MediaOS administrator or support team to enable it for your environment.

Example Integration #

Here’s a basic PHP example of how to generate a JWT token and inject it into the page using MediaOS’s SSO mechanism:

<?php
$payload = [
	'email' => 'email@email.com',
	'first_name' => 'John',
	'last_name' => 'Doe',
	'company' => 'Company',
	'expires' => strtotime('+1 minute'),
	'passwordMD5' => md5('PASSWORD'), // optional
	'forumGroupIds' => [1,2,3],
	'audienceIds' => [1,2,3],
	'avatar' => 'https://domain.com/avatar.jpg',
	'newsletterIds' => [2, 4]
];
?>
<script type="text/javascript">
	window.mediaosSSO = '<?=JWT::encode($payload, 'YOUR JWT SECRET', 'HS256')?>';
</script>
<script type="module" src="https://mos-scripts.com/a/main.js"></script>

Note: Replace 'YOUR JWT SECRET' with the actual JWT secret from your website’s Manage settings in MediaOS.

Payload Field Reference #

Below are the common fields you can pass in the JWT payload:

• email (required) – The user’s email address.
• first_name – User’s first name.
• last_name – User’s last name.
• company – User’s organization.
• expires (required) – UNIX timestamp when this token should expire. Recommended: set to a short duration like strtotime('+1 minute').
• passwordMD5 – MD5-hashed password for setting a password upon import (optional).
• forumGroupIds – Array of forum group IDs the user should join.
• audienceIds – Array of audience IDs the user should be added to.
• avatar – URL to a profile image for the user.
• newsletterIds – Array of newsletter IDs the user should be subscribed to.

Warning: The passwordMD5 field is optional and should only be used if you’re setting or syncing user passwords. Never pass plain-text passwords.

Embedding the Script #

To complete the integration:
Output the JWT token into window.mediaosSSO before loading the MediaOS script.
Then include the following script tag:

<script type="module" src="https://mos-scripts.com/a/main.js"></script>

Tip: This script must be loaded after window.mediaosSSO is defined. For best results, include both immediately before the closing tag of your page.

Troubleshooting #

• JWT tokens are time-sensitive. Make sure the expires value is no more than a few minutes in the future and your server clock is accurate.
• Use a JWT debugging tool like jwt.io to inspect your token and ensure it’s structured properly. Be careful not to paste real tokens with your live secret into public tools.
• If no user is injected after page load, check the browser console for errors and verify the token structure and payload fields.

Suggested Use Cases #

JWT authentication in MediaOS supports a variety of powerful use cases designed to enhance user experience and reduce friction during onboarding. You can use it to automatically subscribe users to newsletters immediately after they complete an external form, eliminating the need for redundant opt-in steps. It also enables seamless login experiences from third-party platforms like CMSs, paywalls, or custom portals, allowing users to access protected MediaOS content without separate credentials. Additionally, JWT can be used to assign users to specific forum groups or audience segments based on how they were acquired—for example, granting exclusive access to those who joined via a partner program, event registration, or gated offer. These use cases help unify your ecosystem while keeping the user journey smooth and secure.