Enable JWTs with sessions

When to use this feature?#

When using SuperTokens our default session management solution will suffice for most use cases. You do not need to use JWTs unless you want to:

Integrate with services that rely on JWT based authentication (For example Hasura)
Integrate SuperTokens with a backend framework that we do not support yet

Enable JWT feature#

NodeJS
GoLang
Python

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

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            jwt: {
                enable: true,
            },
        })
    ]
});

import (
    "github.com/supertokens/supertokens-golang/recipe/session"
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    supertokens.Init(supertokens.TypeInput{
        RecipeList: []supertokens.Recipe{
            session.Init(&sessmodels.TypeInput{
                Jwt: &sessmodels.JWTInputConfig{
                    Enable: true,
                },
            }),
        },
    })
}

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import session

init(
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    framework='...', 
    recipe_list=[
        session.init(
            jwt=session.JWTConfig(
                enable=True
            )
        )
    ]
)

Using a custom issuer#

By default SuperTokens uses your {apiDomain}/auth for the issuer URL. To change the path provide appInfo.apiBasePath when initialising SuperTokens.

In some cases you may need to provide a custom issuer, for example during development you may need to test with external services (like Hasura Cloud). Since the JWKS endpoint is exposed via your backend, JWT verification will fail because the service may not be able to query your local environment (localhost, 127.0.0.1). You can expose your local environment to the internet (using ngrok for example), and set a custom issuer URL instead:

NodeJS
GoLang
Python

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

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            jwt: {
                enable: true,
                /*
                * This is an example of a URL that ngrok generates when
                * you expose localhost to the internet
                */
                issuer: "https://0d53-2405-201-e-d8bd-587b-3674-124d-4208.ngrok.io/auth",
            },
        })
    ]
});

import (
    "github.com/supertokens/supertokens-golang/recipe/session"
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    /*
     * This is an example of a URL that ngrok generates when
     * you expose localhost to the internet
     */
    issuer := "https://0d53-2405-201-e-d8bd-587b-3674-124d-4208.ngrok.io/auth"
    supertokens.Init(supertokens.TypeInput{
        RecipeList: []supertokens.Recipe{
            session.Init(&sessmodels.TypeInput{
                Jwt: &sessmodels.JWTInputConfig{
                    Enable: true,
                    Issuer: &issuer,
                },
            }),
        },
    })
}

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import session

init(
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    
    framework='...', 
    recipe_list=[
        session.init(
            jwt=session.JWTConfig(
                enable=True,
                # This is an example of a URL that ngrok generates when
                # you expose localhost to the internet
                issuer='https://0d53-2405-201-e-d8bd-587b-3674-124d-4208.ngrok.io/auth'
            )
        )
    ]
)

important

Custom issuer URLs must end with your apiBasePath, which is /auth by default