Authentication

StarterStack includes a standard set of apis to handle the following authentication based use cases:

• login - authenticate a user using basic username (email) & password
• logout - invalidate the user login
• reset password - used to securely let a user reset their password with emailed reset password link
• change password - covers the classic "forgot password?" flow

Login

The login api accepts an email and password as the login credentials. It validates the credentials and returns a JSON Web Token (JWT) in a browser session cookie as well as the user object. All subsequent api calls require the JWT cookie to be passed along in the request headers. The browser handles this automatically for you.

Request

curl --location 'http://localhost:8000/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "password": "1234"
}'

Response

{
    "user": {
        "id": 1,
        "first_name": "Kaci",
        "last_name": "Lesch-Ankunding",
        "email": "[email protected]",
        "password": null,
        "password_reset_hash": null,
        "stripe_customer_id": null,
        "deletedAt": null,
        "createdAt": "2024-09-04T21:18:48.000Z",
        "updatedAt": "2024-09-04T21:18:48.000Z"
    }
}

Logout

The logout api is used to delete the browser session cookie that contains the JWT, thus invalidating all subsequent api calls.

Request

curl --location --request GET 'http://localhost:8000/logout' \
--header 'Content-Type: application/json'

Response

HTTP Status 401

Reset Password

The reset password flow provides a more secure way for a logged in user to reset their password. This prevents a hacked account from being able to change a password thus hijacking the user's account.

It works like this:

• The user logs in to their account
• Clicks a reset password button (triggering this api)
• The user's password is reset to a temporary value
• A reset password token is generated and emailed to the user
• The api returns a friendly response meesage you can use to render on screen
• The user receives the email and clicks the reset password link
• Upon successful validation of the reset password token the user is taken to a change password screen

(btw - StarterStack includes all the frontend screens for this flow too!)

Request

curl --location 'http://localhost:8000/reset-password' \
--header 'Content-Type: application/json' \
--header 'Cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsImlhdCI6MTcyNTQ3MTE2NCwiZXhwIjoxNzI1NTU3NTY0fQ.6nzd5f433G-9T-i5t9r4uoWtjDclRp7pfuPtwqGLiT0' \
--data-raw '{
    "email": "[email protected]"
}'

Response

{
    "message": "Your password reset request has been received. A reset link has been sent to Ka******************@y****.c**"
}

Change Password

The change password api covers the classic "Forgot Password?" use case. It's common to have a "Forgot Password?" link on the login page that allows the user to supply an email or user name in order to recover their password.

Here's how this api works in that flow:

• The user is presented with a UI that allows them to enter their email
• The /reset-password api (above) is called
• The user's password is reset to a temporary value
• A reset password token is generated and emailed to the user
• The response message from the /reset-password api is presented on screen to the user
• The user receives the email and follows click the reset password link
• Upon successful validation of the reset password token the user is taken to a change password screen

This is very similar to the reset password flow with the exception that this happens outside of being logged in and the user must be challenged to provide the email on record.

Of course, StarterStack also has this entire UI flow covered for you as well.

Request

curl --location 'http://localhost:8000/change-password' \
--header 'Content-Type: application/json' \
--header 'Cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsImlhdCI6MTcyNTQ3MTE2NCwiZXhwIjoxNzI1NTU3NTY0fQ.6nzd5f433G-9T-i5t9r4uoWtjDclRp7pfuPtwqGLiT0' \
--data '{
    "reset_token": "5ef91d857cf3bcf7857428a6931c80dcde9769b427901cd955fb4281f581bb7e",
    "user_id": 1,
    "password": "1234"
}'

Response

{
    "message": "Your password has been updated."
}