SuperPath Auto Login Integration Documentation

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

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

Partner ID: Provided by the SuperPath Customer Service team.
Partner Secret: Provided by the SuperPath Customer Service team.
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",
  "tenantId": "pznmtt",
  "learningId": "1234567890",
  "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.
tenantId (Optional): The unique identifier of your customer's account within SuperPath. If provided, SuperPath will ensure the user belongs to this tenant. If omitted, SuperPath will attempt to match the email to any account belonging to your partner.
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 partnerSecret to sign the token.

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

Auto Login URL

After generating the token, construct the Auto Login URL:

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

`{partnerId}`: Replace with your unique Partner ID.
`{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.

SuperPath Behavior

Token Verification: SuperPath receives the URL, extracts the token, and verifies it using your partnerSecret.
User Identification:

If tenantId is provided, SuperPath checks if the user with the given email exists within that tenant.

If tenantId is omitted, SuperPath searches for the user across all tenants associated with your partner.
User Authentication/Creation:

If the user exists, they are automatically logged in.

If the user does not exist and auto-user creation is enabled for your partner, a new user account is created and the user is logged in.
Deep Linking (Optional):

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

Security Considerations

Keep your partnerSecret secure. Do not expose it in client-side code.
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: 23/03/2025