Authorization

Auth flow

Registration
Email confirmation
Login

If user has not confirmed its account and trying to sign in, then user will see text like: "You have to confirm you account. Go to your email box and find confirmation link"

Register Req/Res Types

// POST request to backend.com/auth/registration

type RegistrationRequest = {
  name: string;
  surname: string;
  email: string;
  password: string;
  repeatPassword: string;
}

// password must contain:
// * letters,
// * one capitalized letter
// * one digit
// * one symbol like #, $ and etc.
// Also, password must be equal repeatPassword

// email must be as email (yeah ahhahahah)

HTTP/1.1 201 Created
Date: Wed, 08 Jan 2025 12:00:00 GMT

Then user must activate its account by clicking on confirmation link in a mail from backend.
I want to propose this url:
http://backend.com/auth/confirm-account?token=its-access-token-1231123
This is just GET request to /auth/confirm endpoint with ?token query.

If confirming was successful, then we need to redirect user to frontend.com/login (just ask Oleksandr Shtonda about some HTML/JS code for redirecting).

// POST request to backend.com/auth/sign-in

type LoginRequest = {
  email: string;
  password: string;
}

// password must contain:
// * letters,
// * one capitalized letter
// * one digit
// * one symbol like #, $ and etc.

// email must be as email (yeah ahhahahah)

type LoginResponse = {
  accessToken: string;
  refreshToken: string;
  userId: string; // Can we use UUID?
}

The user must be able to sign in ONLY AFTER account confirmation, otherwise we need to send mail to its e-mail again. Frontend must show info about this.
Also, we need GET endpoint backend.com/auth/me to get ability to user to request info about him.
Backend should take accessToken from HTTP header Authorization, decode it, get e-mail from this one, find user in DB and return info.

Reset a password flow

User clicks "forgot a password?"
Frontend redirects the user to reset-password page
User provides its e-mail
User provides a code from its e-mail
User provides a new password
Frontend redirects the user to login page to sign-in

Providing e-mail

type ResetPasswordProvidingEmailRequest = {
  email: string;
}

// email must be email

If e-mail is not e-mail

      HTTP/1.1 400 Bad Request
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If e-mail was not found

      HTTP/1.1 404 Not Found
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If everything is OK

      HTTP/1.1 200 Success
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

Providing confirmation code

type ResetPasswordProvidingCodeRequest = {
  email: string;
  confirmCode: string;
}

// confirmCode must contain 8 digits

If code does not pass validation

      HTTP/1.1 400 Bad Request
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If confirm code is incorrect

      HTTP/1.1 403 Forbidden
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If everything is OK

      HTTP/1.1 200 Success
      Date: Wed, 08 Jan 2025 12:00:00 GMT
      {
        "accessToken": "jwt-token-blablabla"
      }
    

Providing a new password

// Additionally, must be this HTTP Header:
// { "Authorization": "Bearer access-token" }

type ResetPasswordProvidingCodeRequest = {
  password: string;
}

// password must contain:
// * letters,
// * one capitalized letter
// * one digit
// * one symbol like #, $ and etc.

If access token was not provided

      HTTP/1.1 401 Unauthorized
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If password does not pass validation rules

      HTTP/1.1 400 Bad Request
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If new password equals current one

      HTTP/1.1 409 Conflict
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

If everything is OK

      HTTP/1.1 200 Success
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

Logout

The user must be able to log out

Req/Res types

      GET /api/user/logout HTTP/1.1
      Host: example.com
      Authorization: Bearer abc123xyz1-access-jwt...
    

      HTTP/1.1 200 Success
      Date: Wed, 08 Jan 2025 12:00:00 GMT
    

The frontend sends HTTP GET request to the backend. The backend decodes access token and finds the user by user_id (PK) and sets refresh_token field to null. The null value means, that now user is not logged in its account.

Last modified: 13 January 2025

Authorization

Auth flow

Register Req/Res Types

Login Req/Res Types

Reset a password flow

Providing e-mail

Providing confirmation code

Providing a new password

Logout

Req/Res types