Implementing Auto Login (For Customers)

In this article:

• Overview
• How the auto login flow works
• The token payload
• Generating the token
• Building the auto login URL
• Deep linking to a Pathway or assignment
• Things to keep in mind
• FAQs

Overview

Auto Login lets you sign your people into SuperPath from your own platform — an intranet, a portal, an HR system — without them typing anything. Your server builds a JSON Web Token (JWT) describing the user, signs it with a secret that only you and SuperPath hold, and sends the user to a SuperPath URL carrying that token. SuperPath verifies the signature, matches the email address in the token to a user in your account, and completes the sign-in.

This article covers auto login for your own users. If you are a SuperPath partner signing users into your customers' accounts, use the partner documentation instead — it uses a different endpoint and a different secret.

Before you start you will need:

• A paid plan. Auto Login is not available on free accounts.
• Auto Login switched on. Go to Settings → Security → Auto Login and enable Enable auto login for your users, then save. Only Owners and Admins can open Settings.
• Your auto login secret. Enabling the toggle generates one, and Generate New Auto Login Secret issues a replacement. The secret is shown in full only once — copy it straight into your secret store, because afterwards SuperPath only shows a masked version.
• Your Account ID. The six-character identifier shown as Account ID on Settings → General (for example pznmtt).
• A JWT library for your language — Node.js (jsonwebtoken), Python (PyJWT) or equivalent.

Note: Generating a new secret and saving invalidates every token signed with the old one, so roll it out to your integration at the same time.

How the auto login flow works

1. A user clicks a SuperPath link inside your platform.
2. Your server builds the payload, signs it with your auto login secret, and appends the result to the auto login URL as the t query parameter.
3. SuperPath checks that Auto Login is enabled and a secret is set for your account, then verifies the token's signature against that secret.
4. SuperPath reads the email claim and looks up that user inside your account. The user must already exist.
5. SuperPath signs the user in and takes them to their learning — or to the deep link, if you supplied one.

The token payload

SuperPath accepts these claims either at the top level of the payload or nested inside a data object. The example below uses data, which is the form we recommend.

Note: SuperPath does not impose a maximum token lifetime of its own. A token without exp never expires, so always set one and keep it short.

Generating the token

1. Build the payload using the claims above.
2. Sign it with your auto login secret using HS256 — that is the only algorithm SuperPath accepts, and it is the default for a string secret in most libraries.
3. Set an expiry. An hour is generous for a click-through; shorter is better.

Example, using Node.js and jsonwebtoken:

const jwt = require('jsonwebtoken');

const loginSecret = "YOUR_LOGIN_SECRET"; // Replace with your actual secret
const payload = {
  email: "example@example.com",
  firstName: "Jane",
  lastName: "Smith",
  learningId: "1234567890",
  learningType: "pathway"
};

const token = jwt.sign(
  {
    exp: Math.floor(Date.now() / 1000) + 3600, // Token expires in 1 hour
    data: payload,
  },
  loginSecret
);

console.log(token);

The payload itself looks like this:

{
  "email": "example@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "learningId": "1234567890",  //the id of the users learning.  This can be pull from the API
  "learningType": "pathway" // can be "pathway" or "assignment"
}

Building the auto login URL

Send the user to:

https://app.superpath.io/auth/auto/{tenantId}?t={token}

If your account uses a custom domain, use that domain in place of app.superpath.io.

You can also override the destination per link by adding a returnUrl query parameter — for example ?t={token}&returnUrl=/my-learning. It must be a relative path starting with a single /; anything else is ignored for safety. When both are present, returnUrl wins over the deep link inside the token, so you can change where a link lands without re-issuing tokens.

Deep linking to a Pathway or assignment

Supply both learningId and learningType and SuperPath sends the user straight to that item after sign-in:

Any other value produces no deep link, and the user simply lands on their normal start page.

Things to keep in mind

• Auto login never creates users. If the email address in the token does not match an existing user in your account, the sign-in fails. Create your people in SuperPath first (via the app, an import, the API or an HRIS integration).
• firstName and lastName must be present, but they are not used to update the profile. SuperPath validates them and then matches the user on email address alone.
• Auto Login and Restricted View only work for users with password or magic link authentication. SuperPath shows this warning in the Security settings; people who sign in with Google, Microsoft or SSO should keep using their identity provider.
• Keep the secret server-side. Never put it in client-side code, a public repository or a build artefact. If it is ever exposed, generate a new one immediately.
• Tokens are not single-use. SuperPath does not track individual tokens, so a token stays valid until it expires. Keep lifetimes short, use HTTPS everywhere, and avoid logging or emailing the full URL.
• The same secret signs restricted view links. If you also use restricted view, rotating the auto login secret affects both.
• Handle failures on your side too. Check the sign-in worked rather than assuming it did, and give the user a way back to your platform.

FAQs

Where do I find my Account ID?
On Settings → General — it is labelled Account ID and is six characters long.

What does the user see if the token has expired?
A "link has expired" page asking them to contact their administrator for a new link.

What does the user see if the token is invalid, or the email address is not in our account?
An "invalid link" page asking them to contact their administrator. The two cases look the same to the user, so log the outcome on your side to tell them apart.

How do I rotate the secret?
Go to Settings → Security → Auto Login, click Generate New Auto Login Secret, copy the new value while it is on screen, and save. Tokens signed with the previous secret stop working as soon as the change is saved.

Can I use auto login to send someone to a specific piece of learning?
Yes — include learningId and learningType in the payload, or add a returnUrl to the link.

Who can help if the integration is not working?
Contact the SuperPath support team through the chat widget in the app, with the timestamp of a failed attempt and the Account ID you are using.

Updated on: 25/07/2026