Skip to main content
Version: 7.0.X

Overriding APIs

Main interface#

interface APIInterface {
/*
* Refreshs the session if refresh token is found. If no refresh token is found or is expired,
* the default implementation throws an unauthorised error which means the user will need to
* sign-in again.
*
* @method: POST
*
* @params: set it to undefined to disable the API.
* options: see APIOptions below
*/
refreshPOST: undefined | (input: { options: APIOptions }) => Promise<void>;

/*
* API will be called when user wants to logout from the existing session.
*
* @method: POST
*
* @params: set it to undefined to disable the API.
* options: see APIOptions below
*
* @returns: "OK" on successfully logging out the user
*/
signOutPOST:
| undefined
| ((input: {
options: APIOptions;
}) => Promise<{
status: "OK";
}>);

/*
* This is a middleware to be used in the API where you want to verify if an active session
* exists or not for the API call. The default implementation will add a session object to request
* if a active session is found in the request.
*
* @params: options: see APIOptions below
* verifySessionOptions: contain two boolean values: one to enable/disable
* anti-csrf check and another to state if session requirement is optional
*/
verifySession(input: {
verifySessionOptions: VerifySessionOptions | undefined;
options: APIOptions;
}): Promise<void>;
}

Supporting Types#

interface BaseRequest {
original: Express.Request;
getKeyValueFromQuery: (key: string) => Promise<string | undefined>;
getJSONBody: () => Promise<any>;
getMethod: () => HTTPMethod;
getCookieValue: (key_: string) => string | undefined;
getHeaderValue: (key: string) => string | undefined;
getOriginalURL: () => string;
}

interface BaseResponse {
original: Express.Response;
setHeader: (key: string, value: string, allowDuplicateKey: boolean) => void;
setCookie: (
key: string,
value: string,
domain: string | undefined,
secure: boolean,
httpOnly: boolean,
expires: number,
path: string,
sameSite: "strict" | "lax" | "none"
) => void;
setStatusCode: (statusCode: number) => void;
sendJSONResponse: (content: any) => void;
}
interface BaseRequest {
// NestJS uses library-specific types for Request and Response
// You should use the one provided by your underlying framework (the default is Express)
original: Express.Request;
getKeyValueFromQuery: (key: string) => Promise<string | undefined>;
getJSONBody: () => Promise<any>;
getMethod: () => HTTPMethod;
getCookieValue: (key_: string) => string | undefined;
getHeaderValue: (key: string) => string | undefined;
getOriginalURL: () => string;
}

interface BaseResponse {
// NestJS uses library-specific types for Request and Response
// You should use the one provided by your underlying framework (the default is Express)
original: Express.Response;
setHeader: (key: string, value: string, allowDuplicateKey: boolean) => void;
setCookie: (
key: string,
value: string,
domain: string | undefined,
secure: boolean,
httpOnly: boolean,
expires: number,
path: string,
sameSite: "strict" | "lax" | "none"
) => void;
setStatusCode: (statusCode: number) => void;
sendJSONResponse: (content: any) => void;
}
interface APIOptions {
recipeImplementation: RecipeInterface;
config: TypeNormalisedInput;
recipeId: string;
isInServerlessEnv: boolean;
req: BaseRequest;
res: BaseResponse;
}

interface VerifySessionOptions {
antiCsrfCheck?: boolean;
sessionRequired?: boolean;
}
Which frontend SDK do you use?
supertokens-web-js / mobile
supertokens-auth-react