Implementing Auto Login (For Partners)

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
• Automatic user creation
• Things to keep in mind
• FAQs

Overview

Partner auto login lets you sign users into your customers' SuperPath accounts straight from your own platform, without them typing anything. Your server builds a JSON Web Token (JWT) describing the user, signs it with your Partner Secret, and sends the user to a SuperPath URL carrying that token. SuperPath verifies the signature against your partner record, resolves the user, and completes the sign-in.

This article covers auto login for partners and their customers. If you are documenting auto login for your own staff inside a single SuperPath account, use the customer documentation instead — it uses a different endpoint and a different secret.

Before you start you will need:

• Your Partner ID — provided by the SuperPath team. It identifies your partner record.
• Your Partner Secret — provided by the SuperPath team and held against your partner record. It is not self-service: ask the team to change it if it is ever exposed.
• Customer accounts linked to your partner record. Auto login into a specific account only works when that account is linked to your partner record in SuperPath. Accounts you create through the partner API are linked automatically.
• A JWT library for your language — Node.js (jsonwebtoken), Python (PyJWT) or equivalent.

Good to know: Partner auto login is authorised by your Partner Secret, so your customers do not need to switch on the Auto Login setting in their own Settings → Security. That setting governs auto login your customers implement for themselves.

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 Partner Secret, and appends the result to the auto login URL as the t query parameter.
3. SuperPath loads your partner record and verifies the token's signature against your Partner Secret.
4. SuperPath resolves the user inside the customer account named by tenantId — creating them first if automatic user creation is enabled for your partner record. The account must be linked to your partner record, otherwise the request is rejected.
5. SuperPath signs the user in and takes them to their learning — or to the deep link, if you supplied one.
6. If the sign-in cannot be completed and the customer has a custom login domain configured, the browser is sent to that domain instead of showing an error page.

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 Partner 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 partnerSecret = "YOUR_PARTNER_SECRET"; // Replace with your actual secret
const payload = {
  email: "example@example.com",
  firstName: "Jane",
  lastName: "Smith",
  tenantId: "pznmtt",
  learningId: "1234567890",
  learningType: "pathway"
};

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

console.log(token);

The payload itself looks like this:

{
  "email": "example@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "tenantId": "pznmtt",
  "learningId": "1234567890",
  "learningType": "pathway" // can be "pathway" or "assignment"
}

Building the auto login URL

Send the user to:

https://app.superpath.io/auth/partner/{partnerId}?t={token}

If the customer's 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. The id must belong to the same account the user is being signed into.

Automatic user creation

If the token includes tenantId and no user with that email address exists in the account, SuperPath can create one on the fly. This only happens when Automatically create user accounts when using Auto Login is enabled on your partner record — ask the SuperPath team to turn it on. When it is off, the sign-in simply fails.

Users created this way get:

• the Employee role;
• no welcome email and no verification email;
• your externalId (when supplied) as both their external user id and their employee id;
• magic link authentication where the customer's security settings enforce magic link, and email/password otherwise.

Things to keep in mind

• Always send tenantId. It identifies exactly which customer account the user should be signed in to, and it is the only path that can create a missing user. Build it into your integration from the start rather than relying on the email address alone.
• The customer account must be linked to your partner record. A tenantId for an account that is not linked to a partner is rejected.
• Keep the secret server-side. Never put your Partner Secret in client-side code, a public repository or a build artefact. If it is ever exposed, contact the SuperPath team for a replacement straight away.
• 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.
• Failures look the same to the user. An invalid signature, an expired token, an unknown email address and an unlinked account all end at the same "invalid link" page — or a redirect to the customer's custom login domain where one is configured. Log the outcome on your side so you can tell them apart.
• 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

Do my customers need to enable Auto Login in their own Security settings?
No. Partner auto login is authorised by your Partner Secret against your partner record, independently of the customer's own Auto Login setting.

Where do I get my Partner ID and Partner Secret?
Both are issued by the SuperPath team and stored against your partner record. Contact SuperPath support to obtain them, or to have the secret replaced.

What happens if the user does not exist yet?
With tenantId in the token and automatic user creation enabled for your partner record, SuperPath creates the user as an Employee and signs them in. Otherwise the sign-in fails and the user sees the "invalid link" page.

Can I sign a user into an account that is not one of mine?
No. When tenantId is supplied, the account must be linked to your partner record.

Who can help if the integration is not working?
Contact the SuperPath support team, with the timestamp of a failed attempt, your Partner ID and the customer Account ID you are using.

Updated on: 25/07/2026