Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Anonymous / Guest sessions

With anonymous sessions, you can keep track of user's action / data before they login, and then transfer that data to their post login session.

Anonymous sessions have different properties than regular, logged in sessions:

  • The userID of anonymous sessions doesn't matter
  • The security constraints on anonymous sessions is lesser than regular sessions, cause you would want users to be logged in before doing anything sensitive anyway.
  • Each visitor that visits your app / website gets an anonymous session if they don't have one previously. This does not require them to be logged in.
  • We do not want to store anonymous sessions in the database since we run the risk of flodding the db with several sessions that are not that useful to the app.

Given the different characteristics of anonymous sessions, using a simple, long lived JWT is a perfect use case. They can be used to store any information about user's activity, and they don't occupy any database space either.

Creating a JWT#

We can issue JWTs using the Session recipe's Session.createJWT function as shown below:

import Session from "supertokens-node/recipe/session"

async function createAnonymousJWT(payload: any) {
    let jwtResponse = await Session.createJWT({
        key: "value",
        // more payload...
    }, 315360000); // 10 years lifetime
    if (jwtResponse.status === "OK") {
        // Send JWT as Authorization header to M2
        return jwtResponse.jwt;
    }
    throw new Error("Unable to create JWT. Should never come here.")
}
  • As shown in the code above, you can add any payload you like to the JWT. You can even add a sub (userId) payload with a random UUID if you like, or some user ID with a prefix like "G-.." which indicates this is a guest user ID.
  • You could create your own application middleware which will inspects the request and auto adds a JWT to it in the response cookies. This way, whenever a user visits your website, and make an API call, they will get a JWT in their cookies, and you can use that JWT to track their activity.

Verifying the JWT#

caution

Please note that you cannot use the verifySession or getSession functions to verify JWTs from anonymous sessions. The verifySession and getSession check for the presence of certain claims in the JWT (sessionHandle, refreshTokenHash etc...) that are added by the Session recipe for authenticated users. Verification for JWTs from anonymous sessions have to be done manually..

See the manual JWT verification section to see how we can verify the JWT and get its payload.

important

In the section about verification using the public key string, we do not need to set useDynamicAccessTokenSigningKey to true since the createJWT function used above uses the static signing key (kid starting the s-..) by default.

Updating the JWT's payload#

You can create a new JWT with the new payload and add it to the response cookies. This way, the user will have the new JWT in their cookies, and you can use that JWT to track their activity.

Transferring data to a logged in session#

The idea here is that we will override the createNewSession on the backend's Session.init so that whenever the user logs in / signs up, we can transfer the data from the anonymous session to the logged in session.

Our override will attempt to read the request header cookie to get the JWT (assuming that you have added it to the cookies), verify it, and then add the payload to the logged in session.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        // ...
        Session.init({
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        createNewSession: async function (input) {
                            let userId = input.userId;

                            const request = SuperTokens.getRequestFromUserContext(input.userContext);

                            let jwt: string | undefined
                            let jwtPayload = {}

                            if (request !== undefined) {
                                jwt = request.getCookieValue("jwt");
                            } else {
                                /**
                                 * This is possible if the function is triggered from the user management dashboard
                                 * 
                                 * In this case because we cannot read the JWT, we create a session without the custom
                                 * payload properties
                                 */
                            }

                            if (jwt !== undefined) {
                                // verify JWT using a JWT verification library..

                                jwtPayload = { /* ... get from decoded jwt ... */};
                            }

                            // This goes in the access token, and is available to read on the frontend.
                            input.accessTokenPayload = {
                                ...input.accessTokenPayload,
                                ...jwtPayload
                            };

                            return originalImplementation.createNewSession(input);
                        },
                    };
                },
            },
        })
    ]
});
  • In the above code snippet, we attempt to read the JWT from the request header cookie. If it exists, we verify it and then add the payload to the logged in session.
  • If the JWT doesn't exist, or if we cannot verify it, it would be safe to ignore it, and create the logged in session anyway.
  • We assume that the you have saved the JWT in the cookies in with the key of jwt. But if not, you can extract the JWT from the request based on how you have saved it. You can even read the headers from the request. The full interface for the request object is:
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI