> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.superpath.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Implementing Auto Login (For Customers)

# 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

| Claim | Required | Description |
|---|---|---|
| `email` | Yes | The user's email address. Used to find the matching SuperPath user. |
| `firstName` | Yes | The user's first name. Must be present and non-empty. |
| `lastName` | Yes | The user's last name. Must be present and non-empty. |
| `learningId` | No | The id of the Pathway or assignment to deep link the user to. You can read these ids from the SuperPath API. |
| `learningType` | No | Either `pathway` or `assignment`. Required when you supply `learningId`. |
| `exp` | Recommended | Standard JWT expiry, as a Unix timestamp in seconds. See the note below. |

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`:

```js
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:

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

## Building the auto login URL

Send the user to:

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

| Placeholder | Replace with |
|---|---|
| `{tenantId}` | Your six-character Account ID from **Settings → General**. |
| `{token}` | The signed JWT. |

If your account is hosted in the AU or EU region, use `app-au.superpath.io` or `app-eu.superpath.io` in place of `app.superpath.io`. If your account uses a custom domain, use that domain instead.

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:

| `learningType` | Where the user lands |
|---|---|
| `pathway` | The Pathway overview — `/my-pathways/{learningId}/overview` |
| `assignment` | The assignment — `/my-assignments/{learningId}` |

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](https://help.superpath.io/en/article/what-is-restricted-view-for-users-ilvae0), 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.