SuperPath Auto Login Integration Documentation (For Customers)

This document outlines the steps for integrating your platform with SuperPath's Auto Login feature for your users. This feature allows your users to seamlessly access SuperPath without needing to manually log in, providing a smoother user experience.

This article is focused on auto login for your users. If you are a partner please refer to the documentation regarding auto login for Partners

Overview

The Auto Login feature utilizes a secure, encoded JSON Web Token (JWT) passed via a URL parameter to authenticate users directly into SuperPath. SuperPath verifies the token using a shared secret and either logs in an existing user or, if configured, creates a new user on the fly.

Prerequisites

Tenant ID: Your unique 6 character account number that can be accessed in the General Settings
Login Secret: The unique login secret that can be generated from the Security Settings
SuperPath Account: A SuperPath account for your organization.
Basic Understanding of JWTs: Familiarity with JSON Web Tokens and their encoding/decoding.
Programming Language with JWT Library: Such as Node.js (jsonwebtoken), Python (PyJWT), or similar.

Token Payload Structure

The JWT payload must adhere to the following structure:

JSON

{
  "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"
}

email (Required): The user's email address. This is used to identify or create the user in SuperPath.
firstName (Required): The user's first name.
lastName (Required): The user's last name.
learningId (Optional): The identifier of the specific learning pathway or assignment to which you want to deep link the user.
learningType (Optional): Specifies the type of learning (either "pathway" or "assignment"). This is required if learningId is provided.

Token Generation

Construct the Payload: Create a JSON object with the required and optional fields.
Encode the Token: Use a JWT library in your preferred programming language to encode the payload.

Use your loginSecret to sign the token. This secret would have been generated in your Security Settings

Recommended: Set an expiration time for the token to enhance security. A short expiration time (e.g., 1 hour) is recommended.

Example (Node.js using jsonwebtoken)

JavaScript

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

Auto Login URL

After generating the token, construct the Auto Login URL:

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

`{tenantId}`: Replace with your unique Account ID found in General Settings
`{token}`: Replace with the encoded JWT.

Custom Domain (Optional)

If your SuperPath instance uses a custom subdomain, replace app.superpath.io with your custom domain.

Deep Linking (Optional):

If learningId and learningType are provided, SuperPath redirects the user to the specified learning pathway or assignment.

Security Considerations

Keep your loginSecret secure. Do not expose it in client-side code. If this is exposed please re-generate another secret.
Use HTTPS for all communication.
Set an expiration time for your JWTs.
Implement proper error handling. Handle cases where the token is invalid or expired.
Always validate the SuperPath response.

Support

For assistance with your integration, please contact the SuperPath Customer Service team.

Updated on: 05/05/2025