> For the complete documentation index, see [llms.txt](https://help.meltingspot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.meltingspot.io/english/manage-spot/sso.md).

# Single Sign-On

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.

{% hint style="info" %}
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.
{% endhint %}

## **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.

{% tabs %}
{% tab title="Node.js" %}

```javascript
npm install --save jsonwebtoken
```

{% endtab %}

{% tab title="Python" %}
{% code fullWidth="true" %}

```python
pip install PyJWT
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}

```php
composer require firebase/php-jwt
```

{% endtab %}

{% tab title="C#" %}

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

{% endtab %}
{% endtabs %}

### **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. 

You can use all the following fields in the JWT:

<table><thead><tr><th width="152">Parameter</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>sub</code></td><td>string</td><td><p><strong>(required)</strong></p><p>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.</p></td></tr><tr><td><code>firstName</code></td><td>string</td><td><p><strong>(required)</strong></p><p>The first name of the user. It should be 255 characters or less.</p></td></tr><tr><td><code>lastName</code></td><td>string</td><td><p><strong>(required)</strong></p><p>The last name of the user. It should be 255 characters or less.</p></td></tr><tr><td><code>email</code></td><td>string</td><td><p><strong>(required)</strong></p><p>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.</p></td></tr><tr><td><code>title</code></td><td>string</td><td>The job title of the user in plain text format.</td></tr><tr><td><code>avatarUrl</code></td><td>string</td><td>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.</td></tr><tr><td><code>lang</code></td><td>string</td><td><p>The default locale to apply in the application. Currently, MeltingSpot supports:</p><ul><li><code>en</code> for English</li><li><code>fr</code> for French</li><li><code>de</code> for Deutsch</li><li>If not specified or invalid, it will default to <code>en</code>.</li></ul></td></tr><tr><td><code>timezone</code></td><td>string</td><td>The default timezone to apply in the application. If not specified or invalid, it will default to <code>Europe/Paris</code>.</td></tr><tr><td><code>iat</code></td><td>number</td><td>The issue time of the JWT.</td></tr><tr><td><code>exp</code></td><td>number</td><td>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.</td></tr><tr><td><code>groups:join</code></td><td>string[]</td><td>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.</td></tr><tr><td><code>groups:leave</code></td><td>string[]</td><td>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.</td></tr><tr><td><code>customPropertiesValues</code></td><td><em>property type</em></td><td>If you have custom properties, you can specify the value these properties will take on for the member.</td></tr><tr><td><code>domains: set</code></td><td>string[]</td><td>If you have embedded the Spot into several domains, specify which domains the member can have access to. They will be redirected to the <code>default</code> domain key when clicking on a notification email.</td></tr><tr><td><code>domains: unset</code></td><td>string[]</td><td>If you have embedded the Spot into several domains and specified member redirection domains, you can remove them via this parameter (URL of a software for which the member no longer has a license, website whose URL has changed...). You'll need to reuse the keys defined in the <code>set</code> object.</td></tr></tbody></table>

## Mode 1: Authorization URL SSO

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

{% tabs %}
{% tab title="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).
   {% endtab %}

{% tab title="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).

<figure><img src="/files/DWpiYZsKznbeAPx0lqLW" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### 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](#from-your-spot)" flow).\
   \&#xNAN;*�� 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.

<figure><img src="/files/eUViRJX6oJXtbuMA5pP3" alt=""><figcaption></figcaption></figure>

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:

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

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

```url
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`).

{% hint style="info" %}
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`).
{% endhint %}

#### Embed / widgets + SSO = ❤️ <a href="#embed-widgets--sso" id="embed-widgets--sso"></a>

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.

<figure><img src="/files/UTq8eXx4OGStD69OEtPC" alt="SSO authentication in embed and widgets script" width="563"><figcaption></figcaption></figure>

### 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:

{% code overflow="wrap" %}

```
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});
```

{% endcode %}

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.

{% hint style="info" %}

* `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.
  {% endhint %}

## 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 simply log them in without updating their information.
* **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!](/english/manage-spot/audience/members/members-status.md#member-status-update-rules-on-registration-or-connection)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.meltingspot.io/english/manage-spot/sso.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.