🔑Single Sign-On

All it takes is a few lines of code added to your website!

Let your users access your Spot through your own authentication source, without creating a separate MeltingSpot account.

MeltingSpot offers two SSO authentication modes, each independently enabled from your Spot's settings (Settings > Single Sign-On):

• Authorization URL SSO: MeltingSpot redirects the user to your login page, which then redirects them back to MeltingSpot with a signed token.

• Programmatic SSO: Your backend or our SDKs exchange a signed token directly for a session, with no browser redirection.

Both modes rely on the same JWT token and the same SSO secret key (visible at the top of the settings page, in the "Authenticate your users with the SSO key below" field). Only the way this token is delivered to MeltingSpot differs.

Generate an SSO token

Whether you use the "Authorization URL" mode or the "Programmatic" mode, you need to generate a JSON Web Token (JWT) signed with HS256 using your Spot's SSO secret key.

Install JWT library

First, you'll have to install a library that allows you to create the token embedding your user's information.

Node.js

npm install --save jsonwebtoken

Python

pip install PyJWT

PHP

composer require firebase/php-jwt

C#

dotnet add package System.IdentityModel.Tokens.Jwt
dotnet add package Microsoft.IdentityModel.Tokens
dotnet add package Newtonsoft.Json

Create the token

Next, you'll have to prepare a signed JWT defining some or all available user information. You'll have to use the private key copied from the Spot settings.

Node.js

const jwt = require('jsonwebtoken');
const privateKey = 'YOUR_PRIVATE_KEY';
function createToken(user) {
  const userData = {
    sub: user.id, // Your own user ID
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    title: user.title, // optional
    avatarUrl: user.avatarUrl, // optional
    lang: user.lang, // optional
    timezone: user.timezone, // optional
    groups: {
      join: ["groupsId",...],
      leave: ["groupsId",...],
    }, //optional
    domains: {
      // Embed URLs to add or replace, by key
      set: {
        default: "https://app.acme.com/academy",
        customContext: "https://www.acme.com/community",
      },
      // Keys to remove
      unset: ['oldContext'],
    }, //optional
    customPropertiesValues: {
      "customPropertiesSlug1": ["valueSlug",...],
      "customPropertiesSlug2": value,
    }, //optional
  };
  return jwt.sign(userData, privateKey, { algorithm: "HS256" });
}

Python

import jwt

private_key = "YOUR_PRIVATE_KEY"

def create_token(user):
  user_data = {
    'sub': user.id, # Your own user ID
    'firstName': user.firstName,
    'lastName': user.lastName,
    'email': user.email,
    'title': user.title, # optional
    'avatarUrl': user.avatarUrl, # optional
    'lang': user.lang, # optional
    'timezone': user.timezone, # optional
    'groups': {
      'join': ["groupsId",...],
      'leave': ["groupsId",...],
    }, #optional
    'domains': {
      # Embed URLs to add or replace, by key
      'set': {
        'default': "https://app.acme.com/academy",
        'customContext': "https://www.acme.com/community",
      },
      # Keys to remove
      'unset': ['oldContext'],
    }, #optional
    'customPropertiesValues': {
      "customPropertiesSlug1": ["valueSlug",...],
      "customPropertiesSlug2": value,
    }, #optional
  }
  return jwt.encode(user_data, private_key, algorithm='HS256')

PHP

<?php
use Firebase\JWT\JWT;

$privateKey = 'YOUR_PRIVATE_KEY';

function createToken($user) {
    global $privateKey;

    $userData = [
        'sub'                   => $user['id'],          // Your own user ID
        'firstName'             => $user['firstName'],
        'lastName'              => $user['lastName'],
        'email'                 => $user['email'],
        'title'                 => $user['title'] ?? null,      // optional
        'avatarUrl'             => $user['avatarUrl'] ?? null,  // optional
        'lang'                  => $user['lang'] ?? null,       // optional
        'timezone'              => $user['timezone'] ?? null,   // optional
        'groups'                => [
            'join'  => $user['groups']['join'] ?? [],
            'leave' => $user['groups']['leave'] ?? []
        ], // optional
        'domains'               => [
            // Embed URLs to add or replace, by key
            'set'   => [
                'default'       => "https://app.acme.com/academy",
                'customContext' => "https://www.acme.com/community",
                // add other keys if necessary
            ],
            // Keys to remove
            'unset' => ['oldContext']
        ], // optional
        'customPropertiesValues' => [
            "customPropertiesSlug1" => ["valueSlug"],
            "customPropertiesSlug2" => "value"
        ] // optional
    ];

    return JWT::encode($userData, $privateKey, 'HS256');
}
?>

C#

using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;
using Newtonsoft.Json;

public class JwtTokenService
{
    private readonly string _privateKey;

    public JwtTokenService(string privateKey)
    {
        _privateKey = privateKey;
    }

    public string CreateToken(User user)
    {
        var claims = new List<Claim>
        {
            new Claim("sub", user.Id),
            new Claim("firstName", user.FirstName),
            new Claim("lastName", user.LastName),
            new Claim("email", user.Email)
        };

        if (!string.IsNullOrEmpty(user.Title))
            claims.Add(new Claim("title", user.Title));

        if (!string.IsNullOrEmpty(user.AvatarUrl))
            claims.Add(new Claim("avatarUrl", user.AvatarUrl));

        if (!string.IsNullOrEmpty(user.Lang))
            claims.Add(new Claim("lang", user.Lang));

        if (!string.IsNullOrEmpty(user.Timezone))
            claims.Add(new Claim("timezone", user.Timezone));

        if (user.Groups != null)
        {
            if (user.Groups.Join != null && user.Groups.Join.Length > 0)
                claims.Add(new Claim("groups.join", JsonConvert.SerializeObject(user.Groups.Join)));

            if (user.Groups.Leave != null && user.Groups.Leave.Length > 0)
                claims.Add(new Claim("groups.leave", JsonConvert.SerializeObject(user.Groups.Leave)));
        }

        if (user.Domains != null)
        {
            if (user.Domains.Set != null && user.Domains.Set.Count > 0)
                claims.Add(new Claim("domains.set", JsonConvert.SerializeObject(user.Domains.Set)));

            if (user.Domains.Unset != null && user.Domains.Unset.Length > 0)
                claims.Add(new Claim("domains.unset", JsonConvert.SerializeObject(user.Domains.Unset)));
        }
 
        if (user.CustomPropertiesValues != null)
        {
            foreach (var kvp in user.CustomPropertiesValues)
            {
                claims.Add(new Claim($"customPropertiesValues.{kvp.Key}", JsonConvert.SerializeObject(kvp.Value)));
            }
        }

        var tokenHandler = new JwtSecurityTokenHandler();
        var key = Encoding.UTF8.GetBytes(_privateKey);
        
        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(claims),
            SigningCredentials = new SigningCredentials(
                new SymmetricSecurityKey(key), 
                SecurityAlgorithms.HmacSha256)
        };

        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }
}

public class User
{
    public string Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string Title { get; set; }
    public string AvatarUrl { get; set; }
    public string Lang { get; set; }
    public string Timezone { get; set; }
    public Groups Groups { get; set; }
    public Domains Domains { get; set; }
    public Dictionary<string, object> CustomPropertiesValues { get; set; }
}

public class Groups
{
    public string[] Join { get; set; }
    public string[] Leave { get; set; }
}

public class Domains
{
    public Dictionary<string, string> Set { get; set; }
    public string[] Unset { get; set; }
}

You can use all the following fields in the JWT:

Parameter	Type	Description
sub	string	(required) The ID of the user in your product or platform. This value will be stored as an external ID in MeltingSpot. It should be 255 characters or less.
firstName	string	(required) The first name of the user. It should be 255 characters or less.
lastName	string	(required) The last name of the user. It should be 255 characters or less.
email	string	(required) The email of the user. This email address is considered as a verified address. You should make sure you've verified it on your side. It should be 255 characters or less and follow a valid email address format.
title	string	The job title of the user in plain text format.
avatarUrl	string	A full URL to the user's profile picture. It should include https:// or http://. You should make sure it's a valid URL on your side.
lang	string	The default locale to apply in the application. Currently, MeltingSpot supports: en for English fr for French de for Deutsch If not specified or invalid, it will default to en.
timezone	string	The default timezone to apply in the application. If not specified or invalid, it will default to Europe/Paris.
iat	number	The issue time of the JWT.
exp	number	The expiration time of the JWT. Although this value is not required, it's highly recommended to set it to 60 seconds from now. If not set, the token will be valid forever and can introduce security issues.
groups:join	string[]	The groups to which you want to add the member. Simply retrieve the id of the groups in question from the group selection menu of the audience table.
groups:leave	string[]	The groups whose members you wish to remove. Simply retrieve the id of the groups in question from the group selection menu in the audience table.
customPropertiesValues	property type	If you have custom properties, you can specify the value these properties will take on for the member.
domains: set	object	If you have embedded the Spot into several domains, specify the embed URLs the member should be redirected to, as a { key: URL } object (50 keys maximum, 255 characters maximum per URL). The keys passed are added or replaced at each SSO login; other keys already stored are kept. The member will be redirected to the URL of the default key when clicking on a notification email. Learn more
domains: unset	string[]	The keys of the embed URLs to remove from the member (URL of a software for which the member no longer has a license, website whose URL has changed...), 50 keys maximum. unset is applied after set: a key present in both is removed.

Mode 1: Authorization URL SSO

This mode delegates login to your own authentication page via a browser redirection. There are 2 main user journeys:

From your App

1. Your user clicks on a link in your app to enter your Spot.

2. Clicking on this link triggers the creation of a signed token (see above).

3. Your app redirects the user to your Spot and passes the token along.

4. If we can validate the token, we log the user in and identify them using the information passed in the token (like their name and email address).

From your Spot

1. A user who clicks on Login or Join on your Spot (go.meltingspot.io/spot/...) will be redirected to a page on your website (the authorisation URL, see below).

2. On your app, the user will need to login or sign up.

3. Your app will generate a signed token (see how to above).

4. Your app will redirect the user to your Spot and pass the token along.

5. If we can validate the token, we log the user in and identify them using the information passed in the token (like their name and email address).

Implementation

1. Enable JWT SSO in your Spot settings

First, you will need to activate the SSO in your Spot settings :

1. Add an authorisation URL. It is the URL of the page where the user is redirected to be authenticated on your side (2nd bullet point in the "From your Spot" flow). 👀 If you want to run local tests, use 127.0.0.1 in the URL, as localhost URLs are blocked by our system.

2. Copy your private key.

3. Turn SSO on once you are ready.

You will need to create a custom signed link for your app that would automatically pass information to your Spot, such as: the email, first and last name of the member you want to log in.

2. Generate a token

See the section above.

3. Redirection to MeltingSpot

Once the user token has been created, you need to redirect the user to a URL by passing the token as a parameter. This URL is supplied to you as a parameter (redirectUrl) when the user lands on your authorization URL. Basically, it looks like this:

https://go.meltingspot.io/spot/<Your Spot ID>/sso/jwt

You need to add the token as a parameter as follows:

https://go.meltingspot.io/spot/<Your Spot ID>/sso/jwt?ms_token=<Your generated SSO Token>

In most cases, the redirect URL we provide (redirectUrl) also contains a referrerUrl parameter that returns the user to the page they were on when they logged in in SSO mode.

You can force the value of this parameter, but to be valid, the value must represent a path relative to https://go.meltingspot.io and your Spot (e.g. ?referrerUrl=/spot/129487c9-6acc-43d9-ab96-182ded763538/lives).

Your Spot ID is the string following spot/ in your Spot's url (eg: go.meltingspot.io/spot/129487c9-6acc-43d9-ab96-182ded763538 -> Spot ID is 129487c9-6acc-43d9-ab96-182ded763538).

Embed / widgets + SSO = ❤️

Once SSO authentication has been set up for your Spot, you can pass on the JWT token authenticating the user in the Spot embed or widget installation scripts. This will enable every user in your space to access the embed or widget with a connected status. When displaying your Spot in embed, your members will no longer have to click on 'Continue with SSO' to sign up or log in 😉

To do this, you need to add the authToken parameter to the embed or widget installation script parameters.

Mode 2: Programmatic SSO

This mode lets your backend or our Coach SDK exchange a signed token directly for a MeltingSpot session, with no browser redirection.

Configuration

In the "Programmatic SSO" tab of the SSO settings, there's only one setting: a Enable programmatic authentication (SDK) switch.

Using auto-join in the Coach SDK

Once this mode is enabled, pass the generated JWT token (see "Generating a token" above) as authToken to our Coach SDK, and add the autoJoin flag:

import { Coach } from '@meltingspot/coach';await Coach.start({  spotId: 'YOUR_SPOT_ID',  authToken: 'CURRENT_USER_SSO_TOKEN', // the same JWT used for simple authentication  autoJoin: true, // automatically joins and validates the member on the Spot});

The Coach re-authenticates the user with this token, then calls the auto-join API on your behalf, passing it the same signed JWT. The Spot derives first name, last name, email, groups, domains and custom properties directly from the token's claims — no need to send them again separately.

• autoJoin requires authToken: without it, the option is ignored (no join is attempted).

• Auto-join follows the usual status transition rules: a member who has already been rejected or deactivated won't be automatically unblocked.

• If auto-join fails, the Coach's startup fails entirely and the authentication is rolled back — this isn't a silent "best-effort" mechanism, it must be treated as a blocking error on the integration side.

Good to know

• Do I need to enable both modes? No, they're independent. Enable "Authorization URL" if you want a classic SSO login button on your site; enable "Programmatic" if you're integrating our SDKs or calling our API directly. Nothing stops you from enabling both in parallel.

• Do I need to generate a different token for auto-join? No. It's exactly the same JWT, with the same claims and the same secret key as for classic programmatic authentication. The only difference is the autoJoin: true option on the Coach SDK side.

• In Programmatic mode, why is my user authenticated but not a member of the Spot? In "Programmatic" mode, authentication and joining the Spot are two separate steps (unlike "Authorization URL" mode, where they're automatically linked). Use autoJoin: true on the Coach SDK, or handle joining separately via your integration.

• In Programmatic mode, what happens if a member has already been rejected or deactivated? Auto-join follows the existing status transition rules: it won't "unblock" a rejected or deactivated member. The member must be in a state that allows acceptance for auto-join to succeed.

• What happens when a user joins a Spot via SSO? Regardless of the mode used, as long as the token is valid: if the member doesn't exist, we create a new user based on the information passed in the token and log them in. If they already exist, we log them in without updating their profile information (first name, last name, title, avatar…). However, the groups, domains and customPropertiesValues parameters of the token are applied at each login.

• What happens to existing users when I enable SSO? Regardless of the mode: if you enable SSO while you already have registered members on your Spot, no problem — they can keep using their current credentials (email + password). They'll also be able to log in via SSO and add this identification method to their profile, as long as the email associated with their SSO account matches the one used on the Spot.

• My Spot is private, how are sign-ups handled in SSO mode? In "Authorization URL" mode: since the user goes through your login page before joining the Spot, we consider they've already been validated by you — they're automatically accepted, even if the Spot is private. In "Programmatic" mode, this isn't automatic: authentication alone doesn't make the user join the Spot. With autoJoin: true, the member is added following the usual status transition rules (a member who has already been rejected or deactivated won't be unblocked) — so it isn't a guaranteed acceptance like in redirect mode.

• What happens if a user changes their email in my application? The next time they log in to the Spot, we'll treat them as a new user. If they want to access their old profile on the Spot, they'll need to log in via email + password.

• Can I decide the landing page a member opens when they log in via SSO? Yes! When one of your users accesses your Spot from your application, you can use the referrerUrl parameter to send them to any page on your Spot.

• How are handled members' status (Invited / Pending / Declined / Rejected / Deactivated / Left) when they join / reconnect to a Spot with SSO? -> Check it here!