Which frontend SDK do you use?

supertokens-web-js / mobile

supertokens-auth-react

Email Password login

Sign up form

Web

Call the following function when the user clicks on the sign up button.

Via NPM

import { emailPasswordSignUp } from "supertokens-web-js/recipe/thirdpartyemailpassword";
async function signUpClicked(email: string, password: string) {    try {        let response = await emailPasswordSignUp({            formFields: [{                id: "email",                value: email            }, {                id: "password",                value: password            }]        })
        if (response.status === "FIELD_ERROR") {            // one of the input formFields failed validaiton            response.formFields.forEach(formField => {                if (formField.id === "email") {                    // Email validation failed (for example incorrect email syntax),                    // or the email is not unique.                    window.alert(formField.error)                } else if (formField.id === "password") {                    // Password validation failed.                    // Maybe it didn't match the password strength                    window.alert(formField.error)                }            })        } else {            // sign up successful. The session tokens are automatically handled by            // the frontend SDK.            window.location.href = "/homepage"        }    } catch (err: any) {        if (err.isSuperTokensGeneralError === true) {            // this may be a custom error message sent from the API by you.            window.alert(err.message);        } else {            window.alert("Oops! Something went wrong.");        }    }}

Via Script Tag

async function signUpClicked(email: string, password: string) {    try {        let response = await supertokensThirdPartyEmailPassword.emailPasswordSignUp({            formFields: [{                id: "email",                value: email            }, {                id: "password",                value: password            }]        })
        if (response.status === "FIELD_ERROR") {            // one of the input formFields failed validaiton            response.formFields.forEach(formField => {                if (formField.id === "email") {                    // Email validation failed (for example incorrect email syntax),                    // or the email is not unique.                    window.alert(formField.error)                } else if (formField.id === "password") {                    // Password validation failed.                    // Maybe it didn't match the password strength                    window.alert(formField.error)                }            })        } else {            // sign up successful. The session tokens are automatically handled by            // the frontend SDK.            window.location.href = "/homepage"        }    } catch (err: any) {        if (err.isSuperTokensGeneralError === true) {            // this may be a custom error message sent from the API by you.            window.alert(err.message);        } else {            window.alert("Oops! Something went wrong.");        }    }}

Mobile

Call the follwing API when the user clicks on the sign up button (the command below can be tried on your terminal).

curl --location --request POST '<YOUR_API_DOMAIN>/auth/signup' \--header 'rid: thirdpartyemailpassword' \--header 'Content-Type: application/json' \--data-raw '{    "formFields": [{        "id": "email",        "value": "john@example.com"    }, {        "id": "password",        "value": "somePassword123"    }]}'

The response body from the API call has a status property in it:

• status: "OK": User creation was successful. The response also contains more information about the user, for example their user ID.

• status: "FIELD_ERROR": One of the form field inputs failed validation. The response body contains information about which form field input based on the id:

  • The email could fail validation if it's syntactically not an email, of it it's not unique.

  • The password could fail validation if it's not string enough (as defined by the backend password validator).

    Either way, you want to show the user an error next to the input form field.

• status: "GENERAL_ERROR": This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.

The formFields input is a key-value array. You must provide it an email and a password value at a minimum. If you want to provide additional items, for example the user's name or age, you can append it to the array like so:

{    "formFields": [{        "id": "email",        "value": "john@example.com"    }, {        "id": "password",        "value": "somePassword123"    }, {        "id": "name",        "value": "John Doe"    }]}

On the backend, the formFields array will be available to you for consumption.

note

On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.

Checking if email is unique

As a part of the sign up form, you may want to explicitly check that the entered email is unique. Whilst this is already done via the sign up API call, it may be a better UX to warn the user about a non unique email right after they finish typing it.

Web

Via NPM

import { doesEmailExist } from "supertokens-web-js/recipe/thirdpartyemailpassword";
async function checkEmail(email: string) {    try {        let response = await doesEmailExist({            email        });
        if (response.doesExist) {            window.alert("Email already exists. Please sign in instead")        }    } catch (err: any) {        if (err.isSuperTokensGeneralError === true) {            // this may be a custom error message sent from the API by you.            window.alert(err.message);        } else {            window.alert("Oops! Something went wrong.");        }    }}

Via Script Tag

async function checkEmail(email: string) {    try {        let response = await supertokensThirdPartyEmailPassword.doesEmailExist({            email        });
        if (response.doesExist) {            window.alert("Email already exists. Please sign in instead")        }    } catch (err: any) {        if (err.isSuperTokensGeneralError === true) {            // this may be a custom error message sent from the API by you.            window.alert(err.message);        } else {            window.alert("Oops! Something went wrong.");        }    }}

Mobile

curl --location --request GET '<YOUR_API_DOMAIN>/auth/signup/email/exists?email=john@example.com' \--header 'rid: thirdpartyemailpassword'

The response body from the API call has a status property in it:

• status: "OK": The response will also contain a doesExist boolean which will be true if the input email already belongs to an email password user.
• status: "GENERAL_ERROR": This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.

Sign in form

Web

Call the follwing function when the user clicks on the sign in button.

Via NPM

import { emailPasswordSignIn } from "supertokens-web-js/recipe/thirdpartyemailpassword";
async function signInClicked(email: string, password: string) {    try {        let response = await emailPasswordSignIn({            formFields: [{                id: "email",                value: email            }, {                id: "password",                value: password            }]        })
        if (response.status === "FIELD_ERROR") {            response.formFields.forEach(formField => {                if (formField.id === "email") {                    // Email validation failed (for example incorrect email syntax).                    window.alert(formField.error)                }            })        } else if (response.status === "WRONG_CREDENTIALS_ERROR") {            window.alert("Email password combination is incorrect.")        } else {            // sign in successful. The session tokens are automatically handled by            // the frontend SDK.            window.location.href = "/homepage"        }    } catch (err: any) {        if (err.isSuperTokensGeneralError === true) {            // this may be a custom error message sent from the API by you.            window.alert(err.message);        } else {            window.alert("Oops! Something went wrong.");        }    }}

Via Script Tag

async function signInClicked(email: string, password: string) {    try {        let response = await supertokensThirdPartyEmailPassword.emailPasswordSignIn({            formFields: [{                id: "email",                value: email            }, {                id: "password",                value: password            }]        })
        if (response.status === "FIELD_ERROR") {            // one of the input formFields failed validaiton            response.formFields.forEach(formField => {                if (formField.id === "email") {                    // Email validation failed (for example incorrect email syntax).                    window.alert(formField.error)                }            })        } else if (response.status === "WRONG_CREDENTIALS_ERROR") {            window.alert("Email password combination is incorrect.")        } else {            // sign in successful. The session tokens are automatically handled by            // the frontend SDK.            window.location.href = "/homepage"        }    } catch (err: any) {        if (err.isSuperTokensGeneralError === true) {            // this may be a custom error message sent from the API by you.            window.alert(err.message);        } else {            window.alert("Oops! Something went wrong.");        }    }}

Mobile

Call the follwing API when the user clicks on the sign in button (the command below can be tried on your terminal).

curl --location --request POST '<YOUR_API_DOMAIN>/auth/signin' \--header 'rid: thirdpartyemailpassword' \--header 'Content-Type: application/json' \--data-raw '{    "formFields": [{        "id": "email",        "value": "john@example.com"    }, {        "id": "password",        "value": "somePassword123"    }]}'

The response body from the API call has a status property in it:

• status: "OK": User sign in was successful. The response also contains more information about the user, for example their user ID.
• status: "WRONG_CREDENTIALS_ERROR": The input email and password combination is incorrect.
• status: "FIELD_ERROR": This indicates that the input email did not pass the backend validation - probably because it's syntactically not an email. You want to show the user an error next to the email input form field.
• status: "GENERAL_ERROR": This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.

important

On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.

See also

• Post sign in / sign up action
• Adding extra form fields in sign up
• Changing fields validation logic on the backend
• Password hashing algorithms
• Disabling sign up on the backend
• Customising user ID format