JWT Single Sign-On

Sleekplan’s Single Sign-On (SSO) lets users who already have accounts in your application log in to the feedback widget without a separate sign-up step. SSO is built on JSON Web Tokens (JWT), a standard for securely passing authentication data between systems. When a user performs an action that requires authentication — such as voting or submitting feedback — Sleekplan calls $sleek.sso, your server generates a signed token, and Sleekplan accepts it to authenticate the user instantly.

How it works

A user performs an authenticated action (vote, submit feedback) in the widget.
The JavaScript SDK calls $sleek.sso.
Your server generates a JWT signed with your private SSO key.
You pass the token back via the callback() parameter.
Sleekplan verifies the token and logs the user in seamlessly.

Get your SSO secret key

Find your private SSO key in Settings → Developer inside the Sleekplan dashboard at https://app.sleekplan.com/settings/developer.

Your SSO secret key must only ever be used server-side. Never expose it in client-side JavaScript, public repositories, or environment variables that are shipped to the browser. Anyone who obtains the key can generate tokens for any user.

The SSO secret key is available on the Starter and Business plans.

Generate a JWT on your server

Use your language’s JWT library to create a token signed with HMAC SHA-256 (HS256). Replace PRIVATE_SSO_KEY with the key from the previous step. The localUser parameter in each example represents your application’s user record.

Install the library

npm install --save jsonwebtoken

Generate a token

const jwt = require('jsonwebtoken');

const key = 'PRIVATE_SSO_KEY';

function createSSOToken(localUser) {
    const userData = {
        // Required: email address used to uniquely identify the user
        mail: localUser.mail,
        // Recommended: your internal user ID
        id: localUser.id,
        // Optional: lowercase username, letters and numbers only
        name: localUser.name,
        // Optional: URL to the user's avatar image
        img: localUser.imgStr,
        // Optional: user weighting from 1-10 (e.g. based on MRR)
        weight: 4,
        // Optional: additional key-value pairs for the user profile
        meta: {
            companyName: localUser.cName,
        },
    };
    return jwt.sign(userData, key, { algorithm: 'HS256' });
}

Install the library

composer require firebase/php-jwt

Generate a token

use \Firebase\JWT\JWT;

$key = 'PRIVATE_SSO_KEY';

function createSSOToken($localUser) {
    $userData = [
        // Required: email address used to uniquely identify the user
        'mail'   => $localUser['mail'],
        // Recommended: your internal user ID
        'id'     => $localUser['id'],
        // Optional: lowercase username, letters and numbers only
        'name'   => $localUser['name'],
        // Optional: URL to the user's avatar image
        'img'    => $localUser['imgStr'],
        // Optional: user weighting from 1-10 (e.g. based on MRR)
        'weight' => 4,
        // Optional: additional key-value pairs for the user profile
        'meta'   => [
            'companyName' => $localUser['cName'],
        ],
    ];
    return JWT::encode($userData, $key, 'HS256');
}

Install the library

pip install PyJWT

Generate a token

import jwt

PrivateKey = 'PRIVATE_SSO_KEY'

def create_sleekplan_token(localUser):
    user_data = {
        # Required: email address used to uniquely identify the user
        'mail': localUser.mail,
        # Recommended: your internal user ID
        'id': localUser.id,
        # Optional: lowercase username, letters and numbers only
        'name': localUser.name,
        # Optional: URL to the user's avatar image
        'img': localUser.img,
        # Optional: user weighting from 1-10 (e.g. based on MRR)
        'weight': 4,
        # Optional: additional key-value pairs for the user profile
        'meta': {
            'companyName': localUser.cName,
        },
    }
    return jwt.encode(user_data, PrivateKey, algorithm='HS256')

Install the library

# Gemfile
gem 'jwt'

Generate a token

require 'jwt'

PrivateKey = 'PRIVATE_SSO_KEY'

def createSleekplanToken(localUser)
    user_data = {
        # Required: email address used to uniquely identify the user
        mail: localUser.mail,
        # Recommended: your internal user ID
        id: localUser.id,
        # Optional: lowercase username, letters and numbers only
        name: localUser.name,
        # Optional: URL to the user's avatar image
        img: localUser.img,
        # Optional: user weighting from 1-10 (e.g. based on MRR)
        weight: 4,
        # Optional: additional key-value pairs for the user profile
        meta: {
            companyName: localUser.cName,
        },
    }
    JWT.encode(user_data, PrivateKey, 'HS256')
end

Install the libraryAdd the jjwt dependency to your pom.xml or build.gradle.Generate a token

import java.util.HashMap;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

public class CreateSSOToken {
    private static final String PrivateKey = "PRIVATE_SSO_KEY";

    public static String createToken(User user) throws Exception {
        HashMap<String, Object> userData = new HashMap<>();

        // Required: email address used to uniquely identify the user
        userData.put("mail", user.email);
        // Recommended: your internal user ID
        userData.put("id", user.id);
        // Optional: lowercase username, letters and numbers only
        userData.put("name", user.name);
        // Optional: URL to the user's avatar image
        userData.put("img", user.avatarURL);
        // Optional: user weighting from 1-10 (e.g. based on MRR)
        userData.put("weight", 4);

        return Jwts.builder()
                   .setClaims(userData)
                   .signWith(SignatureAlgorithm.HS256, PrivateKey.getBytes("UTF-8"))
                   .compact();
    }
}

Install the library

dotnet add package System.IdentityModel.Tokens.Jwt

Generate a token

using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;

public class LocalUser {
    public string Mail { get; set; }
    public string Id { get; set; }
    public string Name { get; set; }
}

public static class SsoHelper {
    private const string PrivateKey = "PRIVATE_SSO_KEY";

    public static string CreateSsoToken(LocalUser localUser) {
        var claims = new List<Claim> {
            new Claim("mail", localUser.Mail),
            new Claim("id", localUser.Id ?? ""),
            new Claim("name", localUser.Name ?? ""),
            new Claim("weight", "4"),
        };

        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(PrivateKey));
        var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

        var token = new JwtSecurityToken(
            claims: claims,
            signingCredentials: creds
        );

        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

JWT payload attributes

Sleekplan requires an email address to uniquely identify each user. All other attributes are optional but recommended.

Attribute	Required	Description
`mail`	Yes	Email address of the user. Used as the primary identifier for the Sleekplan user record.
`id`	No	Your internal user ID. Highly recommended — allows Sleekplan to match users even if their email address changes.
`name`	No	Username. Use lowercase letters and numbers only — no spaces or special characters.
`full_name`	No	Full display name shown in the Sleekplan UI.
`img`	No	URL to the user’s avatar image.
`weight`	No	User weighting from 1 to 10 (e.g., based on MRR). Used for impact scoring on feedback items.
`meta`	No	Object of additional key-value pairs stored on the user profile.
`groups`	No	Array of companies, teams or workspaces the user belongs to. See Companies and teams below.

Authenticate the user with the token

Once you have a token, pass it to Sleekplan using the method that fits your integration type.

Widget — on page load
Widget — single-page apps
Widget — async / on-demand
Standalone page
Iframe

Set window.SLEEK_USER before the widget snippet loads. This is the simplest approach for server-rendered pages where the user is already authenticated when the page is served.

<!-- User token — place this BEFORE the widget snippet -->
<script type="text/javascript">
window.SLEEK_USER = {
    token: 'YOURTOKEN',
};
</script>

<!-- Sleekplan widget snippet -->
<script type="text/javascript">
window.$sleek = [];
window.SLEEK_PRODUCT_ID = YOUR_PRODUCT_ID;
(function() {
    d = document;
    s = d.createElement("script");
    s.src = "https://client.sleekplan.com/sdk/e.js";
    s.async = 1;
    d.getElementsByTagName("head")[0].appendChild(s);
})();
</script>

Place the window.SLEEK_USER block before the widget snippet. If the snippet loads first, it will not pick up the token.

Call $sleek.setUser() after the SDK has initialized. Use the sleek:init event listener to guarantee the SDK is ready before calling the method.

window.document.addEventListener('sleek:init', () => {
    $sleek.setUser({ token: 'YOURTOKEN' });
}, false);

Always wrap $sleek.setUser() in the sleek:init listener in SPAs. Calling the method before the SDK finishes loading is the most common cause of authentication failures.

Assign a function to $sleek.sso that fetches a fresh token from your server and passes it to the callback. Sleekplan calls this function only when an unauthenticated user performs an action that requires authentication.

$sleek.sso = function(callback) {
    fetch('https://yourserver.com/your_sso_endpoint/')
        .then(response => response.json())
        .then((data) => {
            callback({ token: data.ssoToken });
        });
};

Enable Force single sign-on in your product settings, then set a custom login URL. When an unauthenticated user visits your feedback board, Sleekplan redirects them to your login page. After authenticating, redirect the user back to the board with the token appended.You can pass the token in any of these ways:

Method	How to pass the token
GET parameter	`feedback.yourcompany.com/?sso=YOURTOKEN`
POST parameter	Form field named `sso`
Request header	`Authorization: Bearer YOURTOKEN`

Check the Referer header to determine the correct redirect URL. Ensure your login page is served over HTTPS so the Referer header is sent with the request.

Append the token as a GET parameter to your iframe embed URL:

<iframe
  src="https://embed-PRODUCTID.sleekplan.app/?sso=YOURTOKEN"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

You can also pass the token via POST parameter or Authorization: Bearer header using the same methods described for standalone pages.

Companies and teams

Add a groups array to the token to mirror the accounts in your own system (a company, a team, or a workspace) so admins can see feedback, votes and satisfaction rolled up by account instead of only by individual user. Groups are created and updated automatically from this claim.

Groups require the Business plan or higher. On lower plans a groups claim is accepted and silently ignored, so nothing appears in the dashboard until the workspace upgrades. If groups aren’t showing up, check the plan first.

const userData = {
    mail: localUser.mail,
    id: localUser.id,
    weight: 4,
    meta: {
        companyName: localUser.cName,
    },
    groups: [
        {
            id: 'acme-inc',
            name: 'Acme Inc',
            type: 'company',
            weight: 8,
            mrr: 4200,
            meta: { plan: 'enterprise' },
        },
        {
            id: 'platform-team',
            name: 'Platform Team',
            type: 'team',
        },
    ],
};

Only id is required on each entry. Everything else is optional and defaulted.

string

required

Your identifier for the account. This is what Sleekplan matches on across sign-ins, so treat it as immutable: changing it creates a different group rather than renaming the existing one. Up to 255 characters.

string

Display name. If omitted, the dashboard shows the identifier instead. Up to 255 characters.

string

default:"company"

A free-form label such as company, team, or workspace. Normalized on write, see Type normalization below.

integer

default:"1"

A 0 to 10 prioritization weight for the account’s votes, clamped to that range. The group equivalent of the user-level weight above.

integer

default:"0"

Monthly recurring revenue for the account, in whole units of your workspace’s currency. No minor units, no currency conversion.

object

Flat key/value custom data, string values only. Up to 20 keys per group, each key and value up to 255 characters.

Sync is additive, always

A sign-in creates and updates groups and memberships. It never removes a membership, even for a group that used to appear in the token and no longer does. Removing a customer from a group is an explicit action an admin takes in the dashboard, from the group’s Members tab or the customer’s Groups tab. This is deliberate: groups can also be populated by an external CRM sync running independently of your login flow, and a sign-in that silently pruned what another integration just wrote would destroy data no one asked it to touch.

Only the fields you actually send are touched

Resyncing an account only updates the keys present in that entry. A token that sends { id: 'acme-inc' } on every login updates nothing but the membership itself: it can never blank an mrr or a custom meta key an admin later set by hand. Sending the same entry twice in a row writes nothing the second time. There is one deliberate asymmetry in how metadata is handled:

SSO sync merges a meta object into the group’s existing metadata. A key an admin added by hand survives a later sign-in that doesn’t mention it.
An admin’s edit in the dashboard replaces the whole metadata object. The admin is looking at the full panel and saving what they see, so a key they delete there stays deleted, even though a later sync would have merged it back if the token happened to carry it.

Limits

Bound	Value
Groups applied per SSO token	10
Custom meta keys per group	20
`id`, `name`, meta key and meta value length	255 characters
`type` length	64 characters
Distinct types per workspace	10
`weight`	0 to 10 (default 1)

A bad groups claim never fails the sign-in. Entries past the tenth are dropped, and a malformed entry (not an object, or missing id) is skipped on its own without discarding the rest of the array. Beyond that the two bounds behave differently, so it is worth knowing which is which:

An over-length id or name skips that entry entirely. It is not truncated, because a truncated identifier would silently create or match the wrong group.
An over-length type or meta key/value is truncated, and weight and mrr are clamped into range.

Type normalization

A type is lowercased, its whitespace becomes a hyphen, anything outside a-z, 0-9, _ and - is stripped, repeated hyphens collapse to one, and the result is capped at 64 characters. Key Account becomes key-account. An input that normalizes to nothing, or an omitted type, falls back to company. This exists so Company, company and Company from three different sessions land in the same bucket. Without it a workspace could spend its entire type budget on casing variants of the same account type and see its own numbers split across them.

Distinct types are capped at 10 per workspace. Once a workspace has 10 types in use, an entry with a genuinely new type falls back to company rather than minting an eleventh. A type that already exists is never affected by the cap. Don’t send anything high-cardinality as a type (the company name, an account id): use type for the kind of account and id for the account itself.

When groups appear

Sync runs at sign-in, and sign-in only happens when the widget has no existing session, exactly like weight and meta already work. A change on your side (a renamed account, a new team in the token) shows up the next time that user starts a fresh session, not on their next page view within an existing one. Sync is also dispatched to a background worker rather than run inline, so a sign-in never waits on it and never fails because of it. In practice a synced group or membership can take a moment to appear after the session starts.

User setup

The $sleek.setUser() method and the rest of the user payload.

Companies and teams in the dashboard

How groups look for your team once they start arriving.

Reference

Authentication

JWT Single Sign-On

How it works

JWT payload attributes

Companies and teams

Sync is additive, always

Only the fields you actually send are touched

Limits

Type normalization

When groups appear

User setup

Companies and teams in the dashboard

​How it works

​JWT payload attributes

​Companies and teams

​Sync is additive, always

​Only the fields you actually send are touched

​Limits

​Type normalization

​When groups appear

User setup

Companies and teams in the dashboard

How it works

JWT payload attributes

Companies and teams

Sync is additive, always

Only the fields you actually send are touched

Limits

Type normalization

When groups appear