NodeJS driver for SuperTokens core
This is a NodeJS library that is used to interface between a node API process and the SuperTokens http service.
Learn more at https://supertokens.com
To see documentation, please click here.
Please see the CONTRIBUTING.md file for instructions.
For any queries, or support requests, please email us at team@supertokens.com, or join our Discord server.
Created with :heart: by the folks at supertokens.com.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning
supertokens
code_challenge_method from OIDC provider response to determine whether to use PKCE or not.normalise_url_path_or_throw_error to be case sensitive5.2 to 5.3AccountInfo to AccountInfoInput in various methods for better type safety. This is required in order to allow querying by a single WebAuthn credentialId, while the WebAuthn login method contains an array of credentialIdAdded WebAuthn recipe with authentication support:
Added new API endpoints for WebAuthn operations:
/api/webauthn/email/exists - Check if email exists in system/api/webauthn/options/register - Handle registration options/api/webauthn/options/signin - Handle sign-in options/api/webauthn/signin - Handle WebAuthn sign-in/api/webauthn/signup - Handle WebAuthn sign-up/api/user/webauthn/reset - Handle account recovery/api/user/webauthn/reset/token - Generate recovery tokensAdded WebAuthn support to account linking functionality:
credentialIdAccountInfo type to AccountInfoInput with WebAuthn fieldshasSameWebauthnInfoAs method for credential comparisonUpdated FDI support to 4.1
cookies to string[] instead of string in:authorization in RecipeInterface in oauth2provider recipeauthGET in APIInterface in oauth2provider recipeloginGET in APIInterface in oauth2provider recipegetCookieNameForTokenType config option to allow customizing the cookie name for a token type.getResponseHeaderNameForTokenType config option to allow customizing the response header name for a token type.removeDevice API allowed removing verified TOTP devices without the user completing MFA.networkInterceptor now also gets a new params prop in the request config.customFramework util functions to minimize code required in custom frameworks like remix, astro etc.fastify types based on requirement for the SDK instead of using the original module.TypeProviderunknown instead of string to add support for accepting any type of value in form fields.overwriteSessionDuringSignInUp option.shouldTryLinkingWithSessionUser to sign in/up related APIs (and the related recipe functions)EmailPassword.signInPOSTEmailPassword.signUpPOSTThirdParty.signInUpPOSTPasswordless.createCodePOSTPasswordless.consumeCodePOSTPasswordless.resendCodePOSTEmailPassword.signInEmailPassword.signUpThirdParty.signInUpThirdPary.manuallyCreateOrUpdateUserPasswordless.createCodePasswordless.consumeCodeshouldTryLinkingWithSessionUser is set to false.getOpenIdConfiguration and getOpenIdDiscoveryConfigurationGET, and added the following props:override.openIdFeature from the Session recipe configurationgetJWKS from the OpenId recipe, as it is already exposed by the JWT recipegetAppDirRequestHandler for nextjs will no longer accept a Response object.If you used to use the openIdFeature in the Session recipe, you should now use the OpenId recipe directly instead:
Before:
import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
Session.init({
override: {
openIdFeature: {
jwtFeature: {
functions: originalImplementation => ({
...originalImplementation,
getJWKS: async (input) => {
console.log("getJWKS called");
return originalImplementation.getJWKS(input);
},
})
},
functions: originalImplementation => ({
...originalImplementation,
getOpenIdDiscoveryConfiguration: async (input) => ({
issuer: "your issuer",
jwks_uri: "https://your.api.domain/auth/jwt/jwks.json",
status: "OK"
}),
})
}
}
});
],
});After:
import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import OpenId from "supertokens-node/recipe/openid";
import JWT from "supertokens-node/recipe/jwt";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
Session.init(),
JWT.init({
override: {
functions: originalImplementation => ({
...originalImplementation,
getJWKS: async (input) => {
console.log("getJWKS called");
return originalImplementation.getJWKS(input);
},
})
}
}),
OpenId.init({
override: {
functions: originalImplementation => ({
...originalImplementation,
getOpenIdDiscoveryConfiguration: async (input) => ({
issuer: "your issuer",
jwks_uri: "https://your.api.domain/auth/jwt/jwks.json",
status: "OK"
}),
})
}
});
],
});getAppDirRequestHandler for next.jsBefore:
import { getAppDirRequestHandler } from "supertokens-node/nextjs";
import { NextResponse } from "next/server";
const handleCall = getAppDirRequestHandler(NextResponse);After:
import { getAppDirRequestHandler } from "supertokens-node/nextjs";
const handleCall = getAppDirRequestHandler();psl with tldts to avoid punycode deprecation warning.oidcDiscoveryEndpoint is not defined. It would not be necessary in the cases where other endpoints are already provided.createOrUpdateThirdPartyConfig and deleteThirdPartyConfig which did not take includeInNonPublicTenantsByDefault into account for non-public tenants.shouldDoAutomaticAccountLinking was called without a primary user when linking in some cases.removeFromPayloadByMerge_internal for MultiFactorAuthClaim where it was not retaining other claims while removing the claim from the payload.createOrUpdateThirdPartyConfig and getThirdPartyConfig dashboard APIs to handle boxy SAML inputs.isEmailChangeAllowed was not checking across all tenantsincludeInNonPublicTenantsByDefault for each of the providers. See the migration section below to see how to do this. Note that this only affects non-public tenants when there are no providers added in core.To make all the providers added in the ThirdParty.init available for non-public tenants by default,
Before:
ThirdParty.init({
signInAndUpFeature: {
providers: [
{
config: {
thirdPartyId: "google",
// ... rest of the config
},
},
{
config: {
thirdPartyId: "github",
// ... rest of the config
},
},
],
},
});After:
ThirdParty.init({
signInAndUpFeature: {
providers: [
{
config: {
thirdPartyId: "google",
// ... rest of the config
},
// Add the following line to make this provider available in non-public tenants by default
includeInNonPublicTenantsByDefault: true,
},
{
config: {
thirdPartyId: "github",
// ... rest of the config
},
// Add the following line to make this provider available in non-public tenants by default
includeInNonPublicTenantsByDefault: true,
},
],
},
});thirdPartyConfig for dashboard when OIDC discovery endpoint is added in core.lib/build directory. In those cases we recommend adding index.js to the import path.isEmailChangeAllowed now returns false for unverified addresses if input user is a primary user and there exists another user with the same email address and linking requires verificationshouldRequireVerification is set to true instead of only requiring it for the recipe user.Recipe functions that update the email address of users now call isEmailChangeAllowed to check if the email update should be allowed or not.
isEmailChangeAllowed is now called in functions:updateUser (Passwordless recipe)updateEmailOrPassword (EmailPassword recipe)manuallyCreateOrUpdateUser (ThirdParty recipe)Removes the default maxAgeInSeconds value (previously 300 seconds) in EmailVerification Claim. If the claim value is true and maxAgeInSeconds is not provided, it will not be refetched.
In the multitenancy recipe,
emailPasswordEnabled, passwordlessEnabled, thirdPartyEnabled inputs from createOrUpdateTenant functions.SDK will no longer add .well-known/openid-configuration to the oidcDiscoveryEndpoint config in thirdParty providers. If you have specified any custom oidcDiscoveryEndpoint in the ThirdParty.init or added to the core, please make sure to update them to include .well-known/openid-configuration.
/api/tenants/api/tenant/api/tenant/api/tenant/api/tenant/first-factor/api/tenant/required-secondary-factor/api/tenant/core-config/api/thirdparty/config/api/thirdparty/config/api/thirdparty/configpasswordResetPOST:websiteDomain and apiDomain to core for telemetry.boxyURL is no more mandatory input in additionalConfig while adding boxy-saml provider in thirdParty..well-known/openid-configuration.maxAgeInSeconds value in EmailVerification Claim when the claim value is true. Now, the SDK won't refetch the claim value if maxAgeInSeconds is not provided and claim value is true.jwksRefreshIntervalSec config to session.init to set the default JWKS cache duration. The default is 4 hours.If you were using Multitenancy.createOrUpdateTenant, you should remove the emailPasswordEnabled, passwordlessEnabled, thirdPartyEnabled inputs from the function call, and just use the firstFactors and requiredSecondaryFactors as applicable.
Here are some examples:
Using Emailpassword and ThirdParty login methods
Before:
Multitenancy.createOrUpdateTenant("tenantId", {
emailPasswordEnabled: true,
thirdPartyEnabled: true,
});After:
Multitenancy.createOrUpdateTenant("tenantId", {
firstFactors: ["emailpassword", "thirdparty"],
});Using Passwordless and ThirdParty login methods. Note that for passwordless, you need to specify all the passwordless factorIds you wish to use.
Before:
Multitenancy.createOrUpdateTenant("tenantId", {
passwordlessEnabled: true,
thirdPartyEnabled: true,
});After:
Multitenancy.createOrUpdateTenant("tenantId", {
firstFactors: ["otp-email", "otp-phone", "link-email", "link-phone", "thirdparty"],
});Using EmailPassword, ThirdParty for first factor and phone OTP, TOTP for secondary factors
Before:
Multitenancy.createOrUpdateTenant("tenantId", {
emailPasswordEnabled: true,
thirdPartyEnabled: true,
passwordlessEnabled: true,
firstFactors: ["emailpassword", "thirdparty"],
requiredSecondaryFactors: ["otp-phone", "totp"],
});After:
Multitenancy.createOrUpdateTenant("tenantId", {
firstFactors: ["emailpassword", "thirdparty"],
requiredSecondaryFactors: ["otp-phone", "totp"],
});Enable everything in core so that SDK can configure the required login methods and required secondary factors
Before:
Multitenancy.createOrUpdateTenant("tenantId", {
emailPasswordEnabled: true,
thirdPartyEnabled: true,
passwordlessEnabled: true,
});After:
Multitenancy.createOrUpdateTenant("tenantId", {
firstFactors: null,
requiredSecondaryFactors: null,
});oidcDiscoveryEndpoint in ThirdParty.init:Before:
ThirdParty.init({
signInAndUpFeature: {
providers: [
{
config: {
thirdPartyId: "custom",
clients: [
// ...
],
oidcDiscoveryEndpoint: "https://auth.example.com",
},
},
],
},
});After:
ThirdParty.init({
signInAndUpFeature: {
providers: [
{
config: {
thirdPartyId: "custom",
clients: [
// ...
],
oidcDiscoveryEndpoint: "https://auth.example.com/.well-known/openid-configuration",
},
},
],
},
});oidcDiscoveryEndpoint in core (for custom providers only):For each tenant, do the following
GET /appid-<appId>/<tenantId>/recipe/multitenancy/tenant/v2
You should see the thirdParty providers in the response using response.thirdParty.providers
For each config in providers list, if you have oidcDiscoveryEndpoint in the config, update it to include .well-known/openid-configuration at the end.
Here's a sample code snippet to update the oidcDiscoveryEndpoint:
import Multitenancy from "supertokens-node/recipe/multitenancy";
const tenantsRes = await Multitenancy.listAllTenants();
function isCustomProvider(thirdPartyId: string): boolean {
const customProviders = [
"custom",
//... all your custom thirdPartyIds
];
return customProviders.includes(thirdPartyId);
}
for (const tenant of tenantsRes.tenants) {
for (const provider of tenant.thirdParty.providers) {
if (isCustomProvider(provider.thirdPartyId) && provider.oidcDiscoveryEndpoint !== undefined) {
if (provider.oidcDiscoveryEndpoint.endsWith("/")) {
provider.oidcDiscoveryEndpoint = provider.oidcDiscoveryEndpoint.slice(0, -1);
}
provider.oidcDiscoveryEndpoint = `${provider.config.oidcDiscoveryEndpoint}/.well-known/openid-configuration`;
await Multitenancy.createOrUpdateThirdPartyConfig(tenant.tenantId, provider);
}
}
}refreshPOST and refreshSession now clears all user tokens upon CSRF failures and if no tokens are found. See the latest comment on https://github.com/supertokens/supertokens-node/issues/141 for more details.refreshPOST and refreshSession now clears all user tokens upon CSRF failures and if no tokens are found. See the latest comment on https://github.com/supertokens/supertokens-node/issues/141 for more details.rid query param from:rid header is present in an API call, the routing now not only depends on that. If the SDK cannot resolve a request handler based on the rid, request path and method, it will try to resolve a request handler only based on the request path and method (therefore ignoring the rid header).GET /emailpassword/email/exists => email password, does email exist API (used to be GET /signup/email/exists with rid of emailpassword or thirdpartyemailpassword which is now deprecated)GET /passwordless/email/exists => email password, does email exist API (used to be GET /signup/email/exists with rid of passwordless or thirdpartypasswordless which is now deprecated)GET /passwordless/phonenumber/exists => email password, does email exist API (used to be GET /signup/phonenumber/exists which is now deprecated)If you were using ThirdPartyEmailPassword, you should now init ThirdParty and EmailPassword recipes separately. The config for the individual recipes are mostly the same, except the syntax may be different. Check our recipe guides for ThirdParty and EmailPassword for more information.
If you were using ThirdPartyPasswordless, you should now init ThirdParty and Passwordless recipes separately. The config for the individual recipes are mostly the same, except the syntax may be different. Check our recipe guides for ThirdParty and Passwordless for more information.
input.override object in the ThirdParty providers list.config object in TypeProvider in the provider override. The issue was the originalImplementation.config object did not have the updated config values that was being used in the provider implementation.BaseRequest to handle the form data parser returning FormData instead of the raw parsed object. This is to address/fix the above issues, possibly present in other frameworks.olderCookieDomain config option in the session recipe. This will allow users to clear cookies from the older domain when the cookieDomain is changed.verifySession detects multiple access tokens in the request, it will return a 401 error, prompting a refresh, even if one of the tokens is valid.refreshPOST (/auth/session/refresh by default) API changes:config.olderCookieDomain is not set.olderCookieDomain is specified and multiple refresh/access token cookies exist, without updating the front-token or any of the tokens.This update addresses an edge case where changing the cookieDomain config on the server can lead to session integrity issues. For instance, if the API server URL is 'api.example.com' with a cookie domain of '.example.com', and the server updates the cookie domain to 'api.example.com', the client may retain cookies with both '.example.com' and 'api.example.com' domains, resulting in multiple sets of session token cookies existing.
Previously, verifySession would select one of the access tokens from the incoming request. If it chose the older cookie, it would return a 401 status code, prompting a refresh request. However, the refreshPOST API would then set new session token cookies with the updated cookieDomain, but older cookies will persist, leading to repeated 401 errors and refresh loops.
With this update, verifySession will return a 401 error if it detects multiple access tokens in the request, prompting a refresh request. The refreshPOST API will clear cookies from the old domain if olderCookieDomain is specified in the configuration, then return a 200 status. If olderCookieDomain is not configured, the refreshPOST API will return a 500 error with a message instructing to set olderCookieDomain.
Example:
apiDomain: 'api.example.com'cookieDomain: 'api.example.com'Flow:
domain=api.example.com, but the access token has expired.cookieDomain to .example.com.domain=api.example.com) results in a 401 response.domain=.example.com.olderCookieDomain is not set, the refresh fails with a 500 error. - The user remains stuck until they clear cookies manually or olderCookieDomain is set. - If olderCookieDomain is set, the refresh clears the older cookie, returning a 200 response. - The frontend retries the original API call, sending only the new cookie (domain=.example.com), resulting in a successful request.no-cache header when querying core, so that frameworks like NextJS don't cache GET requests (https://nextjs.org/docs/app/building-your-application/caching#data-cache).local: https://github.com/supertokens/supertokens-node/issues/823resyncSessionAndFetchMFAInfoPUT will throw if the user is in a stuck state, because they are required to complete factors, but they are not allowed to because of some configuration issue.Passwordless:createCodePOST where the flowtype wasn't appropriately set in some MFA casesfirstFactors config of the MultiFactorAuth recipe in createCodePOSTresendCodePOST where the email/text message included a magic link when it shouldn't have in some MFA casesgetTenantLoginMethodsInfo dashboard API to remove querying core in loop and return only firstFactors.useDynamicAccessTokenSigningKey settings by allowing refresh calls to change the signing key type of a sessiondisableCoreCallCache: true, in the config.overwriteSessionDuringSignInUp configuration option to the Session recipecheckCode to Passwordless and ThirdPartyPasswordless recipesverifyCredentials to EmailPassword and ThirdPartyEmailPassword recipesMultiFactorAuth and TOTP recipes. To start using them you'll need compatible versions:userContext:Record<string, any> instead of any as userContext. This means that primitives (strings, numbers) are no longer allowed as userContext.userContext parameter now get a well typed userContext parameter ensuring that the right object is passed to the original implementation callsoverwriteSessionDuringSignInUp: true to the Session recipe config.reason strings of SIGN_IN_NOT_ALLOWED, SIGN_UP_NOT_ALLOWED and SIGN_IN_UP_NOT_ALLOWED responses.Session recipe:AccountLinking recipe:session parameter:createPrimaryUserIdOrLinkAccountsisSignUpAllowedisSignInAllowedisEmailChangeAllowedshouldDoAutomaticAccountLinking callback: it now takes a new (optional) session parameter.EmailPassword:signUpsession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"signInsession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"signInPOSTsignUpPOSTsignUpsession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"signInsession parameterMultitenancy:createOrUpdateTenant: Added optional firstFactors and requiredSecondaryFactors parameters.getTenant: Added firstFactors and requiredSecondaryFactors to the return typelistAllTenants: Added firstFactors and requiredSecondaryFactors to the returned tenantscreateOrUpdateTenant: Now gets optional firstFactors and requiredSecondaryFactors in the input.getTenant: Added firstFactors and requiredSecondaryFactors to the return typelistAllTenants: Added firstFactors and requiredSecondaryFactors to the returned tenantsloginMethodsGET: Now returns firstFactorsPasswordless:revokeCode (and the related overrideable func) can now be called with either preAuthSessionId or codeId instead of only codeId.signInUp, createCode: Takes a new (optional) session parameterconsumeCode:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"consumedDevice if the code was successfully consumedcreateCode: Takes a new (optional) session parameterconsumeCode:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"consumedDevice if the code was successfully consumedcreateCodePOSTresendCodePOSTconsumeCodePOSTbuild function and the fetchValue callback of session claims now take a new currentPayload param.EmailVerificationClaim, UserRoleClaim, PermissionClaim, AllowedDomainsClaim.ThirdParty:manuallyCreateOrUpdateUser:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"signInUp:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"manuallyCreateOrUpdateUsersession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"signInUpPOSTThirdPartyEmailPassword:emailPasswordVerifyCredentialsthirdPartyManuallyCreateOrUpdateUser:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"emailPasswordSignUpsession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"thirdPartySignInUp:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"thirdPartyManuallyCreateOrUpdateUsersession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"emailPasswordSignUpsession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"emailPasswordSignInPOSTemailPasswordSignUpPOSTthirdPartySignInUpPOSTThirdPartyPasswordless:revokeCode (and the related overrideable func) can now be called with either preAuthSessionId or codeId instead of only codeId.thirdPartyManuallyCreateOrUpdateUser:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"passwordlessSignInUp, createCode: Takes a new (optional) session parameterconsumeCode:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"consumedDevice if the code was successfully consumedthirdPartySignInUp:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"thirdPartyManuallyCreateOrUpdateUsersession parameterstatus: "LINKING_TO_SESSION_USER_FAILED"createCode: Takes a new (optional) session parameterconsumeCode:session parameterstatus: "LINKING_TO_SESSION_USER_FAILED"consumedDevice if the code was successfully consumedthirdPartySignInUpPOSTcreateCodePOSTresendCodePOSTconsumeCodePOSTIf you use the userContext or tenantId parameters passed to shouldDoAutomaticAccountLinking, please update your implementation to account for the new parameter.
Before:
AccountLinking.init({
shouldDoAutomaticAccountLinking: async (newAccountInfo, user, tenantId, userContext) => {
return {
shouldAutomaticallyLink: true,
shouldRequireVerification: true,
};
},
});After:
AccountLinking.init({
shouldDoAutomaticAccountLinking: async (newAccountInfo, user, session, tenantId, userContext) => {
return {
shouldAutomaticallyLink: true,
shouldRequireVerification: true,
};
},
});session parameter added to public functionsWe've added a new optional session parameter to many function calls. In all cases, these have been added as the last parameter before userContext, so this should only affect you if you are using that. You only need to pass a session as a parameter if you are using account linking and want to try and link the user signing in/up to the session user.
You can get the necessary session object using verifySession in an API call.
Here we use the example of EmailPassword.signIn but this fits other functions with changed signatures.
Before:
const signInResp = await EmailPassword.signIn("public", "asdf@asdf.asfd", "testpw", { myContextVar: true });After:
const signInResp = await EmailPassword.signIn("public", "asdf@asdf.asfd", "testpw", undefined, { myContextVar: true });fetchValue signature changeIf you use the userContext parameter passed to fetchValue, please update your implementation to account for the new parameter.
Before:
const boolClaim = new BooleanClaim({
key: "asdf",
fetchValue: (userId, recipeUserId, tenantId, userContext) => {
return userContext.claimValue;
},
});After:
const boolClaim = new BooleanClaim({
key: "asdf",
fetchValue: (userId, recipeUserId, tenantId, currentPayload, userContext) => {
return userContext.claimValue;
},
});build signature changeIf you were using the build function for custom or built-in session claims, you should update the call signature to also pass the new parameter.
Before:
Session.init({
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
createNewSession: async function (input) {
input.accessTokenPayload = {
...input.accessTokenPayload,
...(await UserRoleClaim.build(
input.userId,
input.recipeUserId,
input.tenantId,
input.userContext
)),
};
return originalImplementation.createNewSession(input);
},
};
},
},
});After:
Session.init({
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
createNewSession: async function (input) {
input.accessTokenPayload = {
...input.accessTokenPayload,
...(await UserRoleClaim.build(
input.userId,
input.recipeUserId,
input.tenantId,
input.accessTokenPayload,
input.userContext
)),
};
return originalImplementation.createNewSession(input);
},
};
},
},
});Since now sign in/up APIs and functions can be called with a session (e.g.: during MFA flows), you may need to add an extra check to your overrides to account for that:
Before:
// While this example uses Passwordless, all recipes require a very similar change
Passwordless.init({
contactMethod: "EMAIL", // This example will work with any contactMethod
flowType: "USER_INPUT_CODE_AND_MAGIC_LINK", // This example will work with any flowType
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
consumeCode: async (input) => {
// First we call the original implementation of consumeCode.
let response = await originalImplementation.consumeCode(input);
// Post sign up response, we check if it was successful
if (response.status === "OK") {
if (response.createdNewRecipeUser && response.user.loginMethods.length === 1) {
// TODO: post sign up logic
} else {
// TODO: post sign in logic
}
}
return response;
}
}
}
}
}),After:
// While this example uses Passwordless, all recipes require a very similar change
Passwordless.init({
contactMethod: "EMAIL", // This example will work with any contactMethod
flowType: "USER_INPUT_CODE_AND_MAGIC_LINK", // This example will work with any flowType
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
consumeCode: async (input) => {
// First we call the original implementation of consumeCode.
let response = await originalImplementation.consumeCode(input);
// Post sign up response, we check if it was successful
if (response.status === "OK") {
if (input.session === undefined) {
if (response.createdNewRecipeUser && response.user.loginMethods.length === 1) {
// TODO: post sign up logic
} else {
// TODO: post sign in logic
}
}
}
return response;
}
}
}
}
}),Sign in/up APIs and functions will now attempt to link the authenticating user to the session user if a session is available (depending on AccountLinking settings). You can disable this and get the old behaviour by:
Before:
// While this example uses Passwordless, all recipes require a very similar change
Passwordless.init({
contactMethod: "EMAIL", // This example will work with any contactMethod
flowType: "USER_INPUT_CODE_AND_MAGIC_LINK", // This example will work with any flowType
}),After:
// While this example uses Passwordless, all recipes require a very similar change
Passwordless.init({
contactMethod: "EMAIL", // This example will work with any contactMethod
flowType: "USER_INPUT_CODE_AND_MAGIC_LINK", // This example will work with any flowType
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
consumeCode: async (input) => {
input.session = undefined;
return originalImplementation.consumeCode(input);
}
}
}
}
}),createNewSession now defaults to the value of the st-auth-mode header (if available) if the configured getTokenTransferMethod returns any.resetPasswordUsingToken in emailpassword and thirdpartyemailpassword recipe to not include statuses that happen based on email change.withSession, getSSRSession and withPreParsedRequestResponse for Next.js App directory.errorHandler callback function was invoked only upon encountering an error. This behavior has been rectified, and now the callback is invoked in both error and success cases.userContext input to the validate function in form fields. You can use this to fetch the request object from the userContext, read the request body, and then read the other form fields from there. If doing so, keep in mind that for the email and password validators, the request object may not always be available in the validate function, and even if it's available, it may not have the request body of the sign up API since the validate functions are also called from other operations (like in password reset API). For custom form fields that you have added to the sign up API, the request object will always be there in the userContext.node-fetch)verifySession adding generic to extend the fastify base request.getBackwardsCompatibleUserInfo to not throw an error in case of session and user id mismatch.crypto library to enable Apple OAuth usage in Cloudflare Workers.passwordReset in emailpassword recipe for custom frameworks (#746)createResetPasswordLink and sendResetPasswordEmail in thirdpartyemailpassword recipe.networkInterceptor to the TypeInput config.debug property to TypeInput. When set to true, it will enable debug logs.Access-Control-Expose-Headers header value would contain duplicatesnull values in ProviderConfig saved in coregetUsersNewestFirst and getUsersOldestFirst will now properly filter users by tenantId..amazonaws.com) separately while extracting TLDs for SameSite attribute.origin property to appInfo, this can be configured to be a function which allows you to conditionally return the value of the frontend domain. This property will replace websiteDomain in a future release of supertokens-nodewebsiteDomain inside appInfo is now optional. Using origin is recommended over using websiteDomain. This is not a breaking change and using websiteDomain will continue to workvalidateAccessToken to the configuration for social login providers, this function allows you to verify the access token returned by the social provider. If you are using Github as a provider, there is a default implmentation provided for this function.twitter as a built-in thirdparty providerWith this release, we are introducing a new AccountLinking recipe, this will let you:
Check our guide for more information.
To use this you'll need compatible versions:
In this release, we've removed the recipes specific user types and instead introduced a new User class to support the "Primary user" concept introduced by account linking
User class now provides the same interface for all recipes.isPrimary field that you can use to differentiate between primary and recipe usersloginMethods array contains objects that covers all props of the old (recipe specific) user types, with the exception of the id. Please check the migration section below to get the exact mapping between old and new props.loginMethods array should contain exactly 1 element.user.id will be the same as user.loginMethods[0].recipeUserId.getAsString().user.id will change if it is linked to another user.loginMethods array can have 1 or more elements, each corresponding to a single recipe user.user.id will not change even if other users are linked to it.Because of account linking we've introduced a new Primary user concept (see above). In most cases, you should only use the primary user id (user.id or session.getUserId()) if you are associating data to users. Still, in some cases you need to specifically refer to a login method, which is covered by the new RecipeUserId class:
session.getRecipeUserId().loginMethods array of a User object (see above): user.loginMethods[0].recipeUserId.recipeUserId.getAsString().User type, now all functions are using the new generic User type.build function and the fetchValue callback of session claims now take a new recipeUserId param.EmailVerificationClaim, UserRoleClaim, PermissionClaim, AllowedDomainsClaim.createNewSession and createNewSessionWithoutRequestResponsecreatedNewUser has been renamed to createdNewRecipeUser in sign up related APIs and functions
EmailPassword:
getUserById, getUserByEmail. You should use supertokens.getUser, and supertokens. listUsersByAccountInfo insteadconsumePasswordResetToken. This function allows the consumption of the reset password token without changing the password. It will return OK if the token was valid.createNewRecipeUser function that is called during sign up and password reset flow (in case a new email password user is being created on the fly). This is mostly for internal use.recipeUserId is added to the input of getContent of the email delivery configemail was added to the input of createResetPasswordToken , sendResetPasswordEmail, createResetPasswordLinkupdateEmailOrPassword :recipeUserId instead of userIdEMAIL_CHANGE_NOT_ALLOWED_ERROR statussignIn:recipeUserId prop in the status: OK casesignUp:recipeUserId prop in the status: OK caseresetPasswordUsingToken:consumePasswordResetToken and updateEmailOrPasswordsignInPOST:SIGN_IN_NOT_ALLOWEDsignUpPOST:SIGN_UP_NOT_ALLOWEDgeneratePasswordResetTokenPOST:PASSWORD_RESET_NOT_ALLOWEDpasswordResetPOST:user and the email whose password was resetPASSWORD_POLICY_VIOLATED_ERRORcreateEmailVerificationToken, createEmailVerificationLink, isEmailVerified, revokeEmailVerificationTokens , unverifyEmail:recipeUserId instead of userIdsendEmailVerificationEmail :recipeUserId parameterverifyEmailUsingToken:attemptAccountLinking parameterrecipeUserId instead of idsendEmail now requires a new recipeUserId as part of the user infogetEmailForUserId config option was renamed to getEmailForRecipeUserIdverifyEmailPOST, generateEmailVerifyTokenPOST: returns an optional newSession in case the current user session needs to be updatedgetUserById, getUserByEmail, getUserByPhoneNumberupdateUser :recipeUserId instead of userId"EMAIL_CHANGE_NOT_ALLOWED_ERROR and PHONE_NUMBER_CHANGE_NOT_ALLOWED_ERROR statusescreateCodePOST and consumeCodePOST can now return SIGN_IN_UP_NOT_ALLOWEDrecipeUserId is now added to the payload of the TOKEN_THEFT_DETECTED errorcreateNewSession: now takes recipeUserId instead of userIdvalidateClaimsInJWTPayloadrevokeAllSessionsForUser now takes an optional revokeSessionsForLinkedAccounts paramgetAllSessionHandlesForUser now takes an optional fetchSessionsForAllLinkedAccounts paramregenerateAccessToken return value now includes recipeUserIdgetGlobalClaimValidators and validateClaims now get a new recipeUserId paramgetRecipeUserId to the session classsignInUp override:isVerified paramSIGN_IN_UP_NOT_ALLOWEDmanuallyCreateOrUpdateUser:isVerified paramEMAIL_CHANGE_NOT_ALLOWED_ERROR, SIGN_IN_UP_NOT_ALLOWEDgetUserByThirdPartyInfo, getUsersByEmail, getUserByIdsignInUpPOST can now return SIGN_IN_UP_NOT_ALLOWEDgetUserByThirdPartyInfo, getUsersByEmail, getUserByIdthirdPartyManuallyCreateOrUpdateUser:isVerified paramEMAIL_CHANGE_NOT_ALLOWED_ERROR, SIGN_IN_UP_NOT_ALLOWEDthirdPartySignInUp override:isVerified paramSIGN_IN_UP_NOT_ALLOWEDemail was added to the input of createResetPasswordToken , sendResetPasswordEmail, createResetPasswordLinkcreateNewEmailPasswordRecipeUser function that is called during email password sign up and in the “invitation link” flowconsumePasswordResetTokenupdateEmailOrPassword :recipeUserId instead of userIdEMAIL_CHANGE_NOT_ALLOWED_ERROR statusresetPasswordUsingToken:consumePasswordResetToken and updateEmailOrPasswordcreateNewEmailPasswordRecipeUser function that is called during sign up and in the “invitation link” flowemailPasswordSignIn:recipeUserId prop in the status: OK caseemailPasswordSignUp:recipeUserId prop in the status: OK caseemailPasswordSignInPOST:SIGN_IN_NOT_ALLOWEDemailPasswordSignUpPOST:SIGN_UP_NOT_ALLOWEDgeneratePasswordResetTokenPOST:PASSWORD_RESET_NOT_ALLOWEDpasswordResetPOST:user and the email whose password was resetPASSWORD_POLICY_VIOLATED_ERRORthirdPartySignInUpPOST can now return SIGN_IN_UP_NOT_ALLOWEDgetUserByThirdPartyInfo, getUsersByEmail, getUserByPhoneNumber, getUserByIdthirdPartyManuallyCreateOrUpdateUser:isVerified paramEMAIL_CHANGE_NOT_ALLOWED_ERROR, SIGN_IN_UP_NOT_ALLOWEDthirdPartySignInUp override:isVerified paramSIGN_IN_UP_NOT_ALLOWEDupdatePasswordlessUser:recipeUserId instead of userId"EMAIL_CHANGE_NOT_ALLOWED_ERROR and PHONE_NUMBER_CHANGE_NOT_ALLOWED_ERROR statusesthirdPartySignInUpPOST can now return SIGN_IN_UP_NOT_ALLOWEDcreateCodePOST and consumeCodePOST can now return SIGN_IN_UP_NOT_ALLOWEDassociateUserToTenant can now return ASSOCIATION_NOT_ALLOWED_ERRORassociateUserToTenant and disassociateUserFromTenant now take RecipeUserId instead of a string user idRecipeUserId and a generic User classgetUser, listUsersByAccountInfo, convertToRecipeUserId to the main exportsWe've added a generic User class instead of the old recipe specific ones. The mapping of old props to new in case you are not using account-linking:
user.id stays user.id (or user.loginMethods[0].recipeUserId in case you need RecipeUserId)user.email becomes user.emails[0]user.phoneNumber becomes user.phoneNumbers[0]user.thirdParty becomes user.thirdParty[0]user.timeJoined is still user.timeJoineduser.tenantIds is still user.tenantIdsSome functions now require you to pass a RecipeUserId instead of a string user id. If you are using our auth recipes, you can find the recipeUserId as: user.loginMethods[0].recipeUserId (you'll need to worry about selecting the right login method after enabling account linking). Alternatively, if you already have a string user id you can convert it to a RecipeUserId using supertokens.convertToRecipeUserId(userIdString)
// Here res refers to the result the function/api functions mentioned above.
const isNewUser = res.createdNewRecipeUser && res.user.loginMethods.length === 1; const isNewUser = res.user.loginMethods.length === 1;import {isEmailChangeAllowed} from "supertokens-node/recipe/accountlinking";
/// ...
app.post("/change-email", verifySession(), async (req: SessionRequest, res: express.Response) => {
let session = req.session!;
let email = req.body.email;
// ...
if (!(await isEmailChangeAllowed(session.getRecipeUserId(), email, false))) {
// this can come here if you have enabled the account linking feature, and
// if there is a security risk in changing this user's email.
}
// Update the email
let resp = await ThirdPartyEmailPassword.updateEmailOrPassword({
recipeUserId: session.getRecipeUserId(),
email: email,
});
// ...
});admins property which can be used to give Dashboard Users write privileges for the user dashboard.403 for all non-GET requests if the currently logged in Dashboard User is not listed in the admins arrayraw-body dependency.Cache-Control header to /jwt/jwks.json (getJWKSGET)validityInSeconds to the return value of the overrideable getJWKS function.Cache-Control header mentioned above.60 or the value set in the cache-control header returned by the coretenantId to claim build functiontenantId prefixed in the path. e.g. <basePath>/<tenantId>/signinupEmailPassword.createResetPasswordLinkEmailPassword.sendResetPasswordEmailEmailVerification.createEmailVerificationLinkEmailVerification.sendEmailVerificationEmailThirdParty.getProviderThirdPartyEmailPassword.thirdPartyGetProviderThirdPartyEmailPassword.createResetPasswordLinkThirdPartyEmailPassword.sendResetPasswordEmailThirdPartyPasswordless.thirdPartyGetProviderThirdPartyPasswordless.createResetPasswordLinkThirdPartyPasswordless.sendResetPasswordEmailgetUsersOldestFirst & getUsersNewestFirst has mandatory parameter tenantId. Pass 'public' if not using multitenancy.tenantId to EmailDeliveryInterface and SmsDeliveryInterface. Pass 'public' if not using multitenancy.createAndSendCustomEmail and createAndSendCustomTextMessage.tenantId field to TypeEmailPasswordPasswordResetEmailDeliveryInputresetPasswordUsingTokenFeature from TypeInputtenantId param to validate function in TypeInputFormFieldtenantId as first parameter to the following recipe index functions:signUpsignIngetUserByEmailcreateResetPasswordTokenresetPasswordUsingTokentenantId in the input for the following recipe interface functions. If any of these functions are overridden, they need to be updated accordingly:signUpsignIngetUserByEmailcreateResetPasswordTokenresetPasswordUsingTokenupdateEmailOrPasswordtenantId in the input for the following API interface functions. If any of these functions are overridden, they need to be updated accordingly:emailExistsGETgeneratePasswordResetTokenPOSTpasswordResetPOSTsignInPOSTsignUpPOSTtenantId field to TypeEmailVerificationEmailDeliveryInputtenantId as first parameter to the following recipe index functions:createEmailVerificationTokenverifyEmailUsingTokenrevokeEmailVerificationTokenstenantId in the input for the following recipe interface functions. If any of these functions are overridden, they need to be updated accordingly:createEmailVerificationTokenverifyEmailUsingTokenrevokeEmailVerificationTokenstenantId in the input for the following API interface functions. If any of these functions are overridden, they need to be updated accordingly:verifyEmailPOSTtenantId param to validateEmailAddress, validatePhoneNumber and getCustomUserInputCode functions in TypeInputtenantId field to TypePasswordlessEmailDeliveryInput and TypePasswordlessSmsDeliveryInputtenantId in the input to the following recipe index functions:createCodecreateNewCodeForDevicegetUserByEmailgetUserByPhoneNumberupdateUserrevokeCodelistCodesByEmaillistCodesByPhoneNumberlistCodesByDeviceIdlistCodesByPreAuthSessionIdsignInUptenantId in the input for the following recipe interface functions. If any of these functions are overridden, they need to be updated accordingly:createCodecreateNewCodeForDeviceconsumeCodegetUserByEmailgetUserByPhoneNumberrevokeAllCodesrevokeCodelistCodesByEmaillistCodesByPhoneNumberlistCodesByDeviceIdlistCodesByPreAuthSessionIdtenantId in the input for the following API interface functions. If any of these functions are overridden, they need to be updated accordingly:createCodePOSTresendCodePOSTconsumeCodePOSTemailExistsGETphoneNumberExistsGETsignInUpFeature accepts []ProviderInput instead of []TypeProvider. TypeProvider interface is re-written. Refer migration section for more info.signInUp and added manuallyCreateOrUpdateUser instead in the recipe index functions.manuallyCreateOrUpdateUser to recipe interface which is being called by the function mentioned above.manuallyCreateOrUpdateUser recipe interface function should not be overridden as it is not going to be called by the SDK in the sign in/up flow.signInUp recipe interface functions is not removed and is being used by the sign in/up flow.tenantId as first parameter to the following recipe index functions:getUsersByEmailgetUserByThirdPartyInfotenantId in the input for the following recipe interface functions. If any of these functions are overridden, they need to be updated accordingly:getUsersByEmailgetUserByThirdPartyInfosignInUptenantId in the input for the following API interface functions. If any of these functions are overridden, they need to be updated accordingly:authorisationUrlGETsignInUpPOSTsignInUp recipe interface function in thirdparty with new parameters:oAuthTokens - contains all the tokens (access_token, id_token, etc.) as returned by the providerrawUserInfoFromProvider - contains all the user profile info as returned by the providerauthorisationUrlGET APIclientId anymore and accepts clientType instead to determine the matching configpkceCodeVerifier in the response, to support PKCEsignInUpPOST APIclientId, redirectURI, authCodeResponse and code from the inputclientType to determine the matching configappleRedirectHandlerPOSTstate parameter instead of using the websiteDomain config.tenantId as first parameter to the following recipe index functions:createNewSessioncreateNewSessionWithoutRequestResponsevalidateClaimsInJWTPayloadtenantId in the input for the following recipe interface functions. If any of these functions are overridden, they need to be updated accordingly:createNewSessiongetGlobalClaimValidatorstenantId and revokeAcrossAllTenants params to revokeAllSessionsForUser in the recipe interface.tenantId and fetchAcrossAllTenants params to getAllSessionHandlesForUser in the recipe interface.getTenantId function to SessionContainerInterfacetenantId to fetchValue function in PrimitiveClaim, PrimitiveArrayClaim.tenantId as first parameter to the following recipe index functions:addRoleToUserremoveUserRolegetRolesForUsergetUsersThatHaveRoletenantId in the input for the following recipe interface functions. If any of these functions are overridden, they need to be updated accordingly:addRoleToUserremoveUserRolegetRolesForUsergetRolesForUsertenantIdForPasswordPolicy param to EmailPassword.updateEmailOrPassword, ThirdPartyEmailPassword.updateEmailOrPasswordtenantId to Session.revokeAllSessionsForUser. If tenantId is undefined, sessions are revoked across all tenantstenantId to Session.getAllSessionHandlesForUser. If tenantId is undefined, sessions handles across all tenants are returnedtenantId to getUserCount which returns total count across all tenants if not passed.tId to the accessToken payloadincludesAny claim validator to PrimitiveArrayClaimTo call any recipe function that has tenantId added to it, pass 'public'
Before:
EmailPassword.signUp("test@example.com", "password");After:
EmailPassword.signUp("public", "test@example.com", "password");Input for provider array change as follows:
Before:
let googleProvider = thirdParty.Google({
clientID: "...",
clientSecret: "...",
});After:
let googleProvider = {
config: {
thirdPartyId: "google",
clients: [{ clientId: "...", clientSecret: "..." }],
},
};Single instance with multiple clients of each provider instead of multiple instances of them. Also use clientType to differentiate them. clientType passed from the frontend will be used to determine the right config. isDefault option has been removed and clientType is expected to be passed when there are more than one client. If there is only one client, clientType is optional and will be used by default.
Before:
let providers = [
thirdParty.Google({
isDefault: true,
clientID: "clientid1",
clientSecret: "...",
}),
thirdParty.Google({
clientID: "clientid2",
clientSecret: "...",
}),
];After:
let providers = [
{
config: {
thirdPartyId: "google",
clients: [
{ clientType: "web", clientId: "clientid1", clientSecret: "..." },
{ clientType: "mobile", clientId: "clientid2", clientSecret: "..." },
],
},
},
];Change in the implementation of custom providers
ProviderInputgetProfileInfouserInfoEndpoint, userInfoEndpointQueryParams and userInfoMap to fetch the user info from the providergetUserInfo (override example in the next section)Before:
let customProvider = {
id: "custom",
get: (redirectURI, authCodeFromRequest) => {
return {
accessTokenAPI: {
url: "...",
params: {},
},
authorisationRedirect: {
url: "...",
params: {},
},
getClientId: () => {
return "...";
},
getProfileInfo: async (accessTokenAPIResponse) => {
return {
id: "...",
email: {
id: "...",
isVerified: true,
},
};
},
};
},
};After:
let customProvider = {
config: {
thirdPartyId: "custom",
clients: [
{
clientId: "...",
clientSecret: "...",
},
],
authorizationEndpoint: "...",
authorizationEndpointQueryParams: {},
tokenEndpoint: "...",
tokenEndpointBodyParams: {},
userInfoEndpoint: "...",
userInfoEndpointQueryParams: {},
userInfoMap: {
fromUserInfoAPI: {
userId: "id",
email: "email",
emailVerified: "email_verified",
},
},
},
};Also, if the custom provider supports openid, it can automatically discover the endpoints
let customProvider = {
config: {
thirdPartyId: "custom",
clients: [
{
clientId: "...",
clientSecret: "...",
},
],
oidcDiscoveryEndpoint: "...",
userInfoMap: {
fromUserInfoAPI: {
userId: "id",
email: "email",
emailVerified: "email_verified",
},
},
},
};Note: The SDK will fetch the oauth2 endpoints from the provider's OIDC discovery endpoint. No need to /.well-known/openid-configuration to the oidcDiscoveryEndpoint config. For eg. if oidcDiscoveryEndpoint is set to "https://accounts.google.com/", the SDK will fetch the endpoints from "https://accounts.google.com/.well-known/openid-configuration"
Any of the functions in the TypeProvider can be overridden for custom implementation
let customProvider = {
config: {
thirdPartyId: "custom",
clients: [
{
clientId: "...",
clientSecret: "...",
},
],
oidcDiscoveryEndpoint: "...",
userInfoMap: {
fromUserInfoAPI: {
userId: "id",
email: "email",
emailVerified: "email_verified",
},
},
},
override: (originalImplementation) => {
return {
...originalImplementation,
getAuthorisationRedirectURL: async (input) => {
let result = await originalImplementation.getAuthorisationRedirectURL(input);
// ...
return result;
},
exchangeAuthCodeForOAuthTokens: async (input) => {
let result = await originalImplementation.exchangeAuthCodeForOAuthTokens(input);
// ...
return result;
},
getUserInfo: async (input) => {
let result = await originalImplementation.getUserInfo(input);
// ...
return result;
},
};
},
};To get access token and raw user info from the provider, override the signInUp function
ThirdParty.init({
override: {
functions: (oI) => {
return {
...oI,
signInUp: async (input) => {
let result = await oI.signInUp(input);
// result.oAuthTokens.access_token
// result.oAuthTokens.id_token
// result.rawUserInfoFromProvider.fromUserInfoAPI
// result.rawUserInfoFromProvider.fromIdTokenPayload
return result;
},
};
},
},
});Request body of thirdparty signinup API has changed
If using auth code:
Before:
{
"thirdPartyId": "...",
"clientId": "...",
"redirectURI": "...", // optional
"code": "..."
}After:
{
"thirdPartyId": "...",
"clientType": "...",
"redirectURIInfo": {
"redirectURIOnProviderDashboard": "...", // required
"redirectURIQueryParams": {
"code": "...",
"state": "..."
// ... all callback query params
},
"pkceCodeVerifier": "..." // optional, use this if using PKCE flow
}
}If using tokens:
Before:
{
"thirdPartyId": "...",
"clientId": "...",
"redirectURI": "...",
"authCodeResponse": {
"access_token": "...", // required
"id_token": "..."
}
}After:
{
"thirdPartyId": "...",
"clientType": "...",
"oAuthTokens": {
"access_token": "...", // now optional
"id_token": "..."
// rest of the oAuthTokens as returned by the provider
}
}verifySession send the appropriate response instead of throwing (and sending 500) if session validation fails in koa, hapi and loopback (already happening in other frameworks).TRY_REFRESH_TOKEN or UNAUTHORISED error to make debugging easiergetRequestFromUserContext function that can be used to read the original network request from the user context in overridden APIs and recipe functionsgetSession functiongetSession function2.212.8-2.20getAccessTokenPayload will now return standard (sub, iat, exp) claims and some SuperTokens specific claims along the user defined ones in getAccessTokenPayload.sub, iat, exp, sessionHandle, parentRefreshTokenHash1, refreshTokenHash1, antiCsrfTokenmergeIntoAccessTokenPayloadgetAccessToken on the session) if you need a JWTjwt prop in the access token payload is removedaccessTokenPayload to customClaimsInAccessTokenPayload in SessionInformation (the return value of getSessionInformation). This reflects the fact that it doesn't contain some default claims (sub, iat, etc.)useDynamicAccessTokenSigningKey (defaults to true) option to the Session recipe configexposeAccessTokenToFrontendInCookieBasedAuth (defaults to false) option to the Session recipe configgetSessionData to getSessionDataFromDatabase to clarify that it always hits the DBupdateSessionData to updateSessionDataInDatabasesessionData to sessionDataInDatabase in SessionInformation and the input to createNewSessioncheckDatabase param to verifySession and getSessionstatus from getJWKS output (function & API)useStaticSigningKey param to createJWTupdateAccessTokenPayload and regenerateAccessToken from the Session recipe interfacegetAccessTokenLifeTimeMS and getRefreshTokenLifeTimeMS functionsupdateEmailOrPasswordcreateNewSessionWithoutRequestResponse, getSessionWithoutRequestResponse, refreshSessionWithoutRequestResponse to the Session recipe.getAllSessionTokensDangerously to session objects (SessionContainerInterface)attachToRequestResponse to session objects (SessionContainerInterface)exposeAccessTokenToFrontendInCookieBasedAuth: true to the Session recipe config on the backend if you need to access the JWT on the frontend.sub in the code below, but you can replace it with another from the list if you used it in a custom access token payload.subiatexpsessionHandle(await Session.getAccessTokenPayloadSecurely()).jwt update to:let jwt = null;
const accessTokenPayload = await Session.getAccessTokenPayloadSecurely();
if (accessTokenPayload.sub !== undefined) {
jwt = await Session.getAccessToken();
} else {
// This branch is only required if there are valid access tokens created before the update
// It can be removed after the validity period ends
jwt = accessTokenPayload.jwt;
}session.getAccessTokenPayload().jwt please update to:let jwt = null;
const accessTokenPayload = await session.getAccessTokenPayload();
if (accessTokenPayload.sub !== undefined) {
jwt = await session.getAccessToken();
} else {
// This branch is only required if there are valid access tokens created before the update
// It can be removed after the validity period ends
jwt = accessTokenPayload.jwt;
}jwt configurationcreateNewSession function in the session recipe init.iss claim as part of the payload.Before:
import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
Session.init({
jwt: {
enable: true,
issuer: "...",
},
}),
],
});After:
import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
Session.init({
getTokenTransferMethod: () => "header",
override: {
openIdFeature: {
functions: originalImplementation => ({
...originalImplementation,
getOpenIdDiscoveryConfiguration: async (input) => ({
issuer: "your issuer",
jwks_uri: "https://your.api.domain/auth/jwt/jwks.json",
status: "OK"
}),
})
}
}
});
],
});sessionData (not accessTokenPayload)Related functions/prop names have changes (sessionData became sessionDataFromDatabase):
getSessionData to getSessionDataFromDatabase to clarify that it always hits the DBupdateSessionData to updateSessionDataInDatabasesessionData to sessionDataInDatabase in SessionInformation and the input to createNewSessionaccess_token_blacklisting in the core configcheckDatabase to true in the verifySession params.access_token_signing_key_dynamic in the core configuseDynamicAccessTokenSigningKey in the Session recipe config.sub is the protected property we are updating by adding the app prefix):Before:
Session.init({
override: {
functions: (oI) => ({
...oI,
createNewSession: async (input) => {
return oI.createNewSession({
...input,
accessTokenPayload: {
...input.accessTokenPayload,
sub: input.userId + "!!!",
},
});
},
}),
},
});After:
Session.init({
override: {
functions: (oI) => ({
...oI,
getSession: async (input) => {
const result = await oI.getSession(input);
if (result) {
const origPayload = result.getAccessTokenPayload();
if (origPayload.appSub === undefined) {
await result.mergeIntoAccessTokenPayload({ appSub: origPayload.sub, sub: null });
}
}
return result;
},
createNewSession: async (input) => {
return oI.createNewSession({
...input,
accessTokenPayload: {
...input.accessTokenPayload,
appSub: input.userId + "!!!",
},
});
},
}),
},
});createNewSession/refreshSession/getSession:This example uses getSession, but the changes required for the other ones are very similar. Before:
Session.init({
override: {
functions: (oI) => ({
...oI,
getSession: async (input) => {
const req = input.req;
console.log(req);
try {
const session = await oI.getSession(input);
console.log(session);
return session;
} catch (error) {
console.log(error);
throw error;
}
},
}),
},
});After:
Session.init({
override: {
functions: (oI) => ({
...oI,
getSession: async (input) => {
const req = input.userContext._default.request;
console.log(req);
const resp = await oI.getSession(input);
if (resp.status === "OK") {
console.log(resp.session);
} else {
console.log(resp.status);
console.log(resp.error);
}
return resp;
},
}),
},
});getUsersNewestFirst and getUsersOldestFirstcreateNewSession now requires passing the request as well as the response.Authorization header instead of cookiesgetTokenTransferMethod config optionThis example uses express, but the same principle applies for other supported frameworks.
Before:
const app = express();
app.post("/create", async (req, res) => {
await Session.createNewSession(res, "testing-userId", {}, {});
res.status(200).json({ message: true });
});After the update:
const app = express();
app.post("/create", async (req, res) => {
await Session.createNewSession(req, res, "testing-userId", {}, {});
res.status(200).json({ message: true });
});verify function.npm auditSuperTokensError extend the built-in Error class to fix serialization issues.email parameter option in unverifyEmail, revokeEmailVerificationTokens, isEmailVerified, verifyEmailUsingToken, createEmailVerificationToken of the EmailVerification recipe.onInvalidClaim optional error handler to send InvalidClaim error responses.INVALID_CLAIMS to SessionErrors.invalidClaimStatusCode optional config to set the status code of InvalidClaim errors.overrideGlobalClaimValidators to options of getSession and verifySession.mergeIntoAccessTokenPayload to the Session recipe and session objects which should be preferred to the now deprecated updateAccessTokenPayload.EmailVerificationClaim, UserRoleClaim and PermissionClaim. These claims are now added to the access token payload by default by their respective recipes.assertClaims, validateClaimsForSessionHandle, validateClaimsInJWTPayload to the Session recipe to support validation of the newly added claims.fetchAndSetClaim, getClaimValue, setClaimValue and removeClaim to the Session recipe to manage claims.assertClaims, fetchAndSetClaim, getClaimValue, setClaimValue and removeClaim to session objects to manage claims.generateEmailVerifyTokenPOST, verifyEmailPOST, isEmailVerifiedGET.signInUp third party recipe function to accept an email string instead of an object that takes {id: string, isVerified: boolean}.STMP to SMTP everywhere (typo).EmailVerification recipe is now not initialized as part of auth recipes, it should be added to the recipeList directly instead.emailVerificationFeature prop of override) moved from auth recipes into the EmailVerification recipe config.emailVerificationFeature props) moved from auth recipes into the EmailVerification config object root.emailDelivery config of auth recipes into a separate EmailVerification email delivery config.getEmailForUserId in the EmailVerification recipe config. It should now return an object with status.getResetPasswordURL, getEmailVerificationURL, getLinkDomainAndPath. Changing these urls can be done in the email delivery configs instead.unverifyEmail, revokeEmailVerificationTokens, isEmailVerified, verifyEmailUsingToken and createEmailVerificationToken from auth recipes. These should be called on the EmailVerification recipe instead.refreshPOST now returns a Session container object.signOutPOST now takes in an optional session object as a parameter.Before:
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
EmailPassword.init({
emailVerificationFeature: {
// these options should be moved into the config of the EmailVerification recipe
},
override: {
emailVerificationFeature: {
// these overrides should be moved into the overrides of the EmailVerification recipe
}
}
})
]
})After the update:
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
EmailVerification.init({
// all config should be moved here from the emailVerificationFeature prop of the EmailPassword recipe config
override: {
// move the overrides from the emailVerificationFeature prop of the override config in the EmailPassword init here
}
}),
EmailPassword.init()
]
})If you turn on email verification your email-based passwordless users may be redirected to an email verification screen in their existing session. Logging out and logging in again will solve this problem or they could click the link in the email to verify themselves.
You can avoid this by running a script that will:
Something similar to this script:
const SuperTokens = require("supertokens-node");
const Session = require("supertokens-node/recipe/session");
const Passwordless = require("supertokens-node/recipe/passwordless");
const EmailVerification = require("supertokens-node/recipe/emailverification");
SuperTokens.init({
supertokens: {
// TODO: This is a core hosted for demo purposes. You can use this, but make sure to change it to your core instance URI eventually.
connectionURI: "https://try.supertokens.com",
apiKey: "<REQUIRED FOR MANAGED SERVICE, ELSE YOU CAN REMOVE THIS FIELD>",
},
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
EmailVerification.init({
mode: "REQUIRED",
}),
Passwordless.init({
contactMethod: "EMAIL_OR_PHONE",
flowType: "USER_INPUT_CODE_AND_MAGIC_LINK",
}),
Session.init(),
],
});
async function main() {
let paginationToken = undefined;
let done = false;
while (!done) {
const userList = await SuperTokens.getUsersNewestFirst({
includeRecipeIds: ["passwordless"],
limit: 100,
paginationToken,
});
for (const { recipeId, user } of userList.users) {
if (recipeId === "passwordless" && user.email) {
const tokenResp = await EmailVerification.createEmailVerificationToken(user.id, user.email);
if (tokenResp.status === "OK") {
await EmailVerification.verifyEmailUsingToken(tokenResp.token);
}
}
}
done = userList.nextPaginationToken !== undefined;
if (!done) {
paginationToken = userList.nextPaginationToken;
}
}
}
main().then(console.log, console.error);The UserRoles recipe now adds role and permission information into the access token payload by default. If you are already doing this manually, this will result in duplicate data in the access token.
skipAddingRolesToAccessToken and skipAddingPermissionsToAccessToken to true in the recipe init.getServerSideProps). You should handle the new (INVALID_CLAIMS) exception in the same way as you handle UNAUTHORISEDauthUsername option in smtp config for when email is different than the username for auth.userContext optional in sendEmail and sendSms function in all recipe exposed functions.force param from createUserIdMapping and deleteUserIdMapping functionscreateUserIdMapping, getUserIdMapping, deleteUserIdMapping, updateOrDeleteUserIdMappingInfo functionsSessionWrapper.getSession.getSessionInformation now returns undefined is the session does not existupdateSessionData now returns false if the input sessionHandle does not exist.updateAccessTokenPayload now returns false if the input sessionHandle does not exist.regenerateAccessToken now returns undefined if the input access token's sessionHandle does not exist.signIn: async function (input) {
if (input.userContext._default && input.userContext._default.request) {
// do something here with the request object
}
}{status: "GENERAL_ERROR", message: string} as a possible output to all the APIs.FIELD_ERROR output status in third party recipe API to be GENERAL_ERROR.FIELD_ERROR status type in third party signinup API with GENERAL_ERROR.FIELD_ERROR status type from third party signinup recipe function.GENERAL_ERROR to the client.GENERAL_ERROR to the client.getEmailForUserIdForEmailVerification function inside thirdpartypasswordless to take into account passwordless emails and return an empty string in case a passwordless email doesn't exist. This helps situations where the dev wants to customise the email verification functions in the thirdpartypasswordless recipe.emailDelivery user config for Emailpassword, Thirdparty, ThirdpartyEmailpassword, Passwordless and ThirdpartyPasswordless recipes.smsDelivery user config for Passwordless and ThirdpartyPasswordless recipes.Twilio service integartion for smsDelivery ingredient.SMTP service integration for emailDelivery ingredient.Supertokens service integration for smsDelivery ingredient.resetPasswordUsingTokenFeature.createAndSendCustomEmail and emailVerificationFeature.createAndSendCustomEmail have been deprecated.emailVerificationFeature.createAndSendCustomEmail has been deprecated.resetPasswordUsingTokenFeature.createAndSendCustomEmail and emailVerificationFeature.createAndSendCustomEmail have been deprecated.createAndSendCustomEmail and createAndSendCustomTextMessage have been deprecated.createAndSendCustomEmail, createAndSendCustomTextMessage and emailVerificationFeature.createAndSendCustomEmail have been deprecated.Following is an example of ThirdpartyPasswordless recipe migration. If your existing code looks like
import SuperTokens from "supertokens-auth-react";
import ThirdpartyPasswordless from "supertokens-auth-react/recipe/thirdpartypasswordless";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
ThirdpartyPasswordless.init({
contactMethod: "EMAIL_OR_PHONE",
createAndSendCustomEmail: async (input, userContext) => {
// some custom logic
},
createAndSendCustomTextMessage: async (input, userContext) => {
// some custom logic
},
flowType: "...",
emailVerificationFeature: {
createAndSendCustomEmail: async (user, emailVerificationURLWithToken, userContext) => {
// some custom logic
},
},
}),
],
});After migration to using new emailDelivery and smsDelivery config, your code would look like:
import SuperTokens from "supertokens-auth-react";
import ThirdpartyPasswordless from "supertokens-auth-react/recipe/thirdpartypasswordless";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "..."
},
recipeList: [
ThirdpartyPasswordless.init({
contactMethod: "EMAIL_OR_PHONE",
emailDelivery: {
service: {
sendEmail: async (input) => {
let userContext = input.userContext;
if(input.type === "EMAIL_VERIFICATION") {
// some custom logic
} else if (input.type === "PASSWORDLESS_LOGIN") {
// some custom logic
}
}
}
},
smsDelivery: {
service: {
sendSms: async (input) => {
// some custom logic for sending passwordless login SMS
}
}
}
flowType: "..."
})
]
})getUserMetadata to return any type for metadata so that it's easier to use.undefined or not before assigning the email object to the profile info.ThirdPartyPasswordless recipe + tests{}init function will throw error if there are empty items in recipeList when passing the configsignInUp -> thirdPartySignInUpsignUp -> emailPasswordSignUpsignIn -> emailPasswordSignInemailExistsGET -> emailPasswordEmailExistsGETrecipe/thirdpartyemailpassword/index.ts)signInUp -> thirdPartySignInUpsignUp -> emailPasswordSignUpsignIn -> emailPasswordSignInrecipe/user/password/reset (compatibility with CDI 2.12).regenerateAccessToken as a new recipe function for the session recipe.types files. Fixes #230getProfileInfo throws an error, then it is sent as a FIELD_ERROR to the frontend404 response if the API route is not served by the middleware and user has not passed a handler.rid value "anti-csrf": https://github.com/supertokens/supertokens-node/issues/202/signinup POST API to take authCodeResponse XOR code so that it can supprt OAuth via PKCEgetRedirectURI function added to social providers in case we set the redirect_uri on the backend.isDefault param to auth providers so that they can be reused with different credentials.sendHTMLResponse and getFormData functions for frameworksaccessTokenPayload instead of jwtPayload when creating SessionInformation objectSessionRequest as an exported member of session recipe's index filebind(this) when calling original implementationsignInUpPost from thirdpartyemailpassword API interface and replaces it with three APIs: emailPasswordSignInPOST, emailPasswordSignUpPOST and thirdPartySignInUpPOST: https://github.com/supertokens/supertokens-node/issues/192"content-type": "application/json; charset=utf-8" when querying the corecompilerOptions.skipLibCheck in their tsconfig.jsonverifySession middleware ts issue fix for Hapi frameworkverifySession fix for koaframework config option. Default value is express.next parameter. Also the request and response parameter will be of type BaseRequest and BaseResponse.createNewSession, getSession and refreshSession can by of any type and not express.Request and express.Response.import {middleware, errorHandler} from "supertokens-node/framework/express"). Also, errorHandler may not be there for few frameworksas it may not be required.import {verifySession} from "supertokens-node/recipe/session/framework/express").handleAPIRequest in recipe modules will no longer take next parameter. Also the request and response parameter will be of type BaseRequest and BaseResponse.handleAPIRequest in recipe modules will return boolean. If the response is sent from handleAPIRequest, the function will return true else it will return false.handleError in recipe modules will no longer take next parameter. Also the request and response parameter will be of type BaseRequest and BaseResponse. If error is not handled by the function, it will rethrow the error.true will be returned else false.verifySession which was defined in middleware.ts file is now removed.UNKNOWN_USER_ID to UNKNOWN_USER_ID_ERROR to make it more consistent with other status types: https://github.com/supertokens/supertokens-node/issues/166import {middleware, errorHandler} from "supertokens-node")import {verifySession} from "supertokens-node/recipe/session")ThirdParty recipe, for type TypeProviderGetResponse, the field authorisationRedirect.params will be of type { [key: string]: string | ((request: BaseRequest) => string) }. Earlier, the request was of type express.Request.APIOptions, their will be no next parameter. Also the request and response parameter will be of type BaseRequest and BaseResponse.getUserByEmail in recipe/thirdpartyemailpassword/recipeImplementation/emailPasswordRecipeImplementation.ts to use getUsersByEmail instead of getUserByEmailsupertokens.getUserCount, supertokens.getUsersNewestFirst or supertokens.getUsersOldestFirst):ThirdParty.getUserCount(), ThirdParty.getUsersNewestFirst(), ThirdParty.getUsersOldestFirstEmailPassword.getUserCount(), EmailPassword.getUsersNewestFirst(), EmailPassword.getUsersOldestFirstThirdPartyEmailPassword.getUserCount(), ThirdPartyEmailPassword.getUsersNewestFirst(), ThirdPartyEmailPassword.getUsersOldestFirstSession.getSessionInformation())Session.getSessionData(), Session.getJWTPayload()emailVerificationRecipeImplementation in all auth recipe APIOptions so that APIs can access the email verification implementation.getUserByEmail in thirdpartyemailpassword and replaces it with getUsersByEmail.updateEmailOrPassword recipe function to emailpassword and thirdpartyemailpassword recipes: https://github.com/supertokens/supertokens-core/issues/275getSession function instead of verifySession middleware in prebuilt APIsgetSession third param is no longer a booleanhandleCustomFormFieldsPostSignUp.superTokensMiddleware from NextJS as it is no longer needed and was deprecated.superTokensNextWrapper functionsetJwtPayload and setSessionData get all formFields paramdisableDefaultImplementation with setting functions in override > apis to undefined.setJwtPayload and setSessionData as deprecated.enableAntiCsrf config to antiCsrf.apiWebProxyPath config. Use appInfo -> apiGatewayPath instead.req.body is undefined or if it is bufferapiGatewayPath in appInfo during init. This deprecates apiWebProxyPath.req.body is not undefined - as long as it's not a valid JSON.idRefreshToken is present in the request, but the refresh token is missing, we clear the idRefreshToken as well.init is called multiple times, it does not throw an errorgetCORSAllowedHeaders function to be used by cors middlewareinit function inside app.use()Access-Control-Allow-Credentials header valuerevokeMultipleSessions functionupdateJWTPayload functionrevokeSessionUsingSessionHandle => revokeSession