MERN Stack - Server

MongoDB - Express - React - Redux - React Native - NodeJS

Source Code
t-ho Jan 09, 2020 Mar 03, 2022

CI Testing code style: prettier license

mern-logo

API

General

Health Check

  • Method: GET
  • Content-Type: application/json
  • Endpoint
/api/alive
  • Response payload
Property Name Type Description
status string Service status

Sample response

{
  "status": "pass"
}

Authentication

Sign Up

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/signup
  • Resquest Body Payload
Property Name Type Required Description
username string Yes Username
email string Yes Email
password string Yes Password
firstName string No First name
lastName string No Last name

Sample request body payload

{
  "username": "user",
  "email": "user@tdev.app",
  "password": "password",
  "firstName": "User",
  "lastName": "Account"
}
  • Response Payload
Property Name Type Description
message string Message

Sample response

{
  "message": "Your account has been created successfully"
}

Sign In With Email

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/signin
  • Resquest Body Payload
Property Name Type Required Description
username string Yes Either username or email is required
email string Yes Either username or email is required
password string Yes Password

Sample request body payload

{
  "email": "user@tdev.app",
  "password": "password"
}
  • Response Payload
Property Name Type Description
token string JWT token
expiresAt number Expires at time (seconds)
user object User info

Sample response

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjMiLCJ1c2VySWQiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjIiLCJpYXQiOjE1ODE4MDk2ODYsImV4cCI6MTU4Njk5MzY4Nn0.6rjee9HpGVP-IsKfGBAiqU8Y6FHuuBN25odKZExig7liOhJd2lq_eUn8JUOtz7QpRX5RvGYzbzlxdRED0boNVA",
  "expiresAt": 1586993686,
  "signedInWith": "local",
  "user": {
    "id": "5e47a9600cac851790f29662",
    "username": "user",
    "email": "user@tdev.app",
    "status": "active",
    "firstName": "User",
    "lastName": "Account",
    "role": "user",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "local": {
        "userId": "5e47a9600cac851790f29662"
      }
    },
    "createdAt": "2020-02-15T08:18:40.429Z",
    "updatedAt": "2020-02-15T08:18:40.429Z"
  }
}

Sign In With Apple

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/apple
  • Resquest Body Payload
Property Name Type Required Description
code string Yes The Apple authorization code
user string No The user object

Sample request body payload

{
  "code": "c99a498c3274c4536b25fa497ab843fd6.0.srqwv.j5XSP_uk87Et1xsKlMUEFw",
  "user: {
    "name": {
      "firstName": "User",
      "lastName": "Account"
    }
  }
}
  • Response Payload
Property Name Type Description
token string JWT token
expiresAt number Expires at time (seconds)
signedInWith string The auth provider that the user used to sign in with
user object User info

Sample response

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjMiLCJ1c2VySWQiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjIiLCJpYXQiOjE1ODE4MDk2ODYsImV4cCI6MTU4Njk5MzY4Nn0.6rjee9HpGVP-IsKfGBAiqU8Y6FHuuBN25odKZExig7liOhJd2lq_eUn8JUOtz7QpRX5RvGYzbzlxdRED0boNVA",
  "expiresAt": 1586993686,
  "signedInWith": "apple",
  "user": {
    "id": "5e47a9600cac851790f29662",
    "username": "sn824b2zsd",
    "email": "sn824b2zsd@privaterelay.appleid.com",
    "status": "active",
    "firstName": "User",
    "lastName": "Account",
    "role": "user",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "apple": {
        "userId": "001765.bfe650a68ab3407caf263826e4fac791.2416",
      }
    },
    "createdAt": "2020-02-15T08:18:40.429Z",
    "updatedAt": "2020-02-15T08:18:40.429Z"
  }
}

Sign In With Facebook

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/facebook
  • Resquest Body Payload
Property Name Type Required Description
accessToken string Yes The Facebook access token
refreshToken string No The Facebook refresh token

Sample request body payload

{
  "accessToken": "EAAx0076n7rwBAE76vGbLS0y5kK01uZB7urxtWC1eh30NIZBO4G0XH1gA2CSRGtNFxaZBKiUlT0nZAPk8AzyiK1DGg47HOaWnkfaG4FyZCPhiEQZByPbP9dWB6JZBw6GiIXPGmnSdkIAzuT5MEK5slyAEs8jZCazvs4wziZBdx2eIsWeSN5Hhxy9RRrZCSHrWGm8hvI9DrxZCkeR4BWVxLN6YItOuZC1A80VctLAZD"
}
  • Response Payload
Property Name Type Description
token string JWT token
expiresAt number Expires at time (seconds)
signedInWith string The auth provider that the user used to sign in with
user object User info

Sample response

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjMiLCJ1c2VySWQiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjIiLCJpYXQiOjE1ODE4MDk2ODYsImV4cCI6MTU4Njk5MzY4Nn0.6rjee9HpGVP-IsKfGBAiqU8Y6FHuuBN25odKZExig7liOhJd2lq_eUn8JUOtz7QpRX5RvGYzbzlxdRED0boNVA",
  "expiresAt": 1586993686,
  "signedInWith": "facebook",
  "user": {
    "id": "5e47a9600cac851790f29662",
    "username": "user",
    "email": "user@tdev.app",
    "status": "active",
    "firstName": "User",
    "lastName": "Account",
    "role": "user",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "facebook": {
        "userId": "197154714957030",
        "picture": "picture-url.jpg"
      }
    },
    "createdAt": "2020-02-15T08:18:40.429Z",
    "updatedAt": "2020-02-15T08:18:40.429Z"
  }
}

Sign In With Google

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/google
  • Resquest Body Payload
Property Name Type Required Description
idToken string Yes The Google ID token

Sample request body payload

{
  "idToken": "eyJhbGciOiJSUzI1NiksImtpZCI6ImYwOTJiNjEyZTliNjQ0N2RlYjEwNjg1YmI4ZmZhOGFlNjJmNmFhOTEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJhenAiOiIxMzQ2NzUwNjIwMDMtbHRhbDY2cGo3bHR0NHF1ZW9rdjdkbjg4b3E4cHZmbjIuYXBwcy5nb29nbGV1c2VyY29udGVudC5Yb20iLCJhdWQiOiIxMzQ2NzUwNjIwMDMtdM5nZmZvazNuOGV1ZjUzczlxcWZsOWt1c3BqaDRggGUuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJzdWIiOiIxMDgwMzQyNzQ2NzMzMTk2NDI2NjIiLCJlbWFpbCI6InRlc3Rlci5obXRAZ21haWwuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImF0X2hhc2giOiJOMDRZdFNZZVl5WUoycS1VNUhZTmlnIiwibm9uY2UiOiJOenlrbW9rNnZZVzAzUURHZ2UyLXVSREozaEJoUTljSm5qX0pyRXdLRlNFIiwibmFtZSI6InQgaG8iLCJwaWN0dXJlIjoiaHR0cHM6Ly9saDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2EtL0FPaDE0R2h0ck8zOHF4bFM5R1ZqUHdXVEdhSVlZZ0lIYUtKVVlxY3F1Z1JsPXM5Ni1jIiwiZ2l2ZW5fbmFtZSI6InQiLCJmYW1pbHlfbmFtZSI6ImhvIiwibG9jYWxlIjoiZW4iLCJpYXQiOjE2MDUwODY2NDIsImV4cCI6MTYwNTA5MDI0Mn0.142V5YJdBaoR_jPK7-g87cgLFFkFWxu1fbxEXRh8HHQLveCmiMgb9XvoZyxpe6hthNUAyzB4Jtq-ijgzwaEY6W4OLr3sczngi9SluqmM2YORLa0p6PIPgJKr-e3rJjIQBgM_4Ye-p8fAl8YzZyHduPzT7gS2Xie5HUZ9BHOh4jtPpKx6z1goE4Ev9apdyCVt6XbVzN5gsBHEHM3YQAU0KN4WbJzEvYSkaTjoRAGE3_naaTzv5EvyiR08n5lB9Y37LMEJeohf_SMCpaXsyWkzduf2aP2Rb-KUH_EkJXsYZVuDr9lP5FzGUDgbeeyv08HThYGEOPuwAEfKSRVbcOH3mw"
}
  • Response Payload
Property Name Type Description
token string JWT token
expiresAt number Expires at time (seconds)
signedInWith string The auth provider that the user used to sign in with
user object User info

Sample response

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjMiLCJ1c2VySWQiOiI1ZTQ3YTk2MDBjYWM4NTE3OTBmMjk2NjIiLCJpYXQiOjE1ODE4MDk2ODYsImV4cCI6MTU4Njk5MzY4Nn0.6rjee9HpGVP-IsKfGBAiqU8Y6FHuuBN25odKZExig7liOhJd2lq_eUn8JUOtz7QpRX5RvGYzbzlxdRED0boNVA",
  "expiresAt": 1586993686,
  "signedInWith": "google",
  "user": {
    "id": "5e47a9600cac851790f29662",
    "username": "user",
    "email": "user@tdev.app",
    "status": "active",
    "firstName": "User",
    "lastName": "Account",
    "role": "user",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "google": {
        "userId": "114383861774342288272",
        "picture": "picture-url.jpg"
      }
    },
    "createdAt": "2020-02-15T08:18:40.429Z",
    "updatedAt": "2020-02-15T08:18:40.429Z"
  }
}

Send Verification Email

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/send-token
  • Resquest Body Payload
Property Name Type Required Description
email string Yes Email
tokenPurpose string Yes Token purpose. It must be verify-email

Sample request body payload

{
  "email": "user@tdev.app",
  "tokenPurpose": "verify-email",
}
  • Response Payload
Property Name Type Description
message string Message

Sample response

{
  "message": "A verification email has been sent to your email"
}

Verify Email Code

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/verify-email/:token
  • Resquest Body Payload
Property Name Type Required Description
password string Yes The current password

Sample request body payload

{
  "password": "password"
}
  • Response Payload
Property Name Type Description
message string Message

Sample response

{
  "message": "Email verified"
}

Send Password Reset Email

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/send-token
  • Resquest Body Payload
Property Name Type Required Description
email string Yes Email
tokenPurpose string Yes Token purpose. It must be reset-password

Sample request body payload

{
  "email": "user@tdev.app",
  "tokenPurpose": "reset-password",
}
  • Response Payload
Property Name Type Description
message string Message

Sample response

{
  {
    "message": "A password-reset email has been sent to your email"
  }
}

Confirm Password Reset

  • Method: POST
  • Content-Type: application/json
  • Endpoint
/api/auth/reset-password/:token
  • Resquest Body Payload
Property Name Type Required Description
email string Yes Email
password string Yes New password

Sample request body payload

{
  "email": "user@tdev.app",
  "password: "new-password"
}
  • Response Payload
Property Name Type Description
message string Message

Sample response

{
  "message": "Password reset"
}

Invalidate All JWT Tokens

  • Method: POST
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/auth/invalidate-all-jwt-tokens
  • Resquest Body Payload

No payload required

  • Response payload
Property Name Type Description
message string The verification status

Sample response

{
  "message": "All JWT tokens have been invalidated",
}

Verify JWT Token

  • Method: POST
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/auth/verify-jwt-token
  • Resquest Body Payload
Property Name Type Required Description
refreshToken boolean No If true, a new JWT token will be included in the response
refreshUser boolean No If true, an user object will be included in the response

Sample request body payload

{
  "refreshToken": true,
}
  • Response payload
Property Name Type Description
message string The verification status
token string New JWT token
expiresAt number Expires at time (seconds)

Sample response

{
  "message": "JWT token is valid",
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZTI3ZTQ4OTY2OGEyYjQxZWUxNmY3NDIiLCJ1c2VySWQiOiI1ZTI0ZjhkM2M1ZGZmZjFmYzk1NDQ3ZDUiLCJpYXQiOjE1Nzk2NzY1OTgsImV4cCI6MTU4NDg2MDU5OH0.7DjINccJtzowF0Nf2DnMoBtKpWEzRKLqcpzzIByHuwnqXRHKduYHGfOgf1ak9t2qLHQzPwMw-FxOGtZGVvAucA",
  "expiresAt": 1584860598,
}

Profile

Get User Profile

  • Method: GET
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/profiles
  • Response payload
Property Name Type Description
profile object User profile JSON object

Sample response

{
  "profile": {
    "id": "5e47a9600cac851790f29662",
    "username": "user",
    "email": "user@tdev.app",
    "status": "active",
    "firstName": "User",
    "lastName": "Account",
    "role": "user",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "local": {
        "userId": "5e47a9600cac851790f29662"
      }
    },
    "createdAt": "2020-02-15T08:18:40.429Z",
    "updatedAt": "2020-02-15T08:18:40.429Z"
  }
}

Get User Public Profile

  • Method: GET

  • Content-Type: application/json

  • Endpoint
/api/profiles/:userId
  • Response payload
Property Name Type Description
profile object User profile JSON object

Sample response

{
  "profile": {
    "id": "5e24d42cf7dddf012cd496b2",
    "username": "sarah",
    "firstName": "Sarah",
    "lastName": "Connor",
    "createdAt": "2020-01-19T22:11:56.779Z"
  }
}

Update User Profile

  • Method: PUT
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/profiles
  • Resquest Body Payload
Property Name Type Required Description
firstName string No New first name
lastName string No New last name

Sample request body payload

{
  "firstName: "Sarah"
}
  • Response payload
Property Name Type Description
user object The updated user object
updatedFields string array Fields has been updated

Sample response

{
  "user": {
    "id": "5ed72abbdbc55ffdf6d221c3",
    "username": "root",
    "email": "root@tdev.app",
    "status": "active",
    "firstName": "Sarah",
    "lastName": "Account",
    "role": "root",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false
    },
    "provider": {
      "local": {
        "userId": "5ed72abbdbc55ffdf6d221c3"
      }
    },
    "createdAt": "2020-06-03T04:44:43.980Z",
    "updatedAt": "2020-10-16T18:37:12.632Z"
  },
  "updatedFields": [
    "firstName"
  ]
}

Update Password

  • Method: PUT
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/profiles/password
  • Resquest Body Payload
Property Name Type Required Description
currentPassword string Yes Current password
password string Yes New password

Sample request body payload

{
  "currentPassword: "current-password",
  "password: "new-password",
}
  • Response payload
Property Name Type Description
token string New JWT token
expiresAt number Expires at time (seconds)

Sample response

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZTI3ZTQ4OTY2OGEyYjQxZWUxNmY3NDIiLCJ1c2VySWQiOiI1ZTI0ZjhkM2M1ZGZmZjFmYzk1NDQ3ZDUiLCJpYXQiOjE1Nzk2NzY1OTgsImV4cCI6MTU4NDg2MDU5OH0.7DjINccJtzowF0Nf2DnMoBtKpWEzRKLqcpzzIByHuwnqXRHKduYHGfOgf1ak9t2qLHQzPwMw-FxOGtZGVvAucA",
  "expiresAt": 1584860598,
}

Users

Get Users

  • Method: GET
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/users
  • Resquest Query
Property Name Type Required Description
limit number No Limit number (Default: 30)
skip number No Offset number (Default: 0)
sort string No Sort criteria (example: “createdAt” or “-createdAt”)
username string No Username
email string No Email
firstName string No First name
lastName string No Last name
status string No Status. It could be “active”, “disabled” or “unverified-email”]
role string No User role. It could be “root”, “admin” or “user”
permissions string No User permissions. (example: ‘readPosts’ or ‘editPosts’).

Note: When permissions is specified (without role), it will include admin and root users in the response.

  • Response Payload
Property Name Type Description
users object array A list of users
usersCount number A total number of users

Sample response

{
  "users": [
    {
      "id": "5e24d42cf7dddf012cd496b2",
      "username": "tester",
      "email": "test@test.com",
      "status": "active",
      "firstName": "Sarah",
      "lastName": "Connor",
      "role": "root",
      "permissions": {
        "userInsert": false,
        "userModify": false,
        "userRead": false,
        "postInsert": false,
        "postModify": false,
        "postRead": true
      },
      "provider": {
        "local": {
          "userId": "5e24d42cf7dddf012cd496b2"
        }
      },
      "createdAt": "2020-01-19T22:11:56.779Z",
      "updatedAt": "2020-01-19T23:18:47.897Z"
    },
    {
      "id": "5e24db1d560ba309f0b0b5a8",
      "username": "tester2",
      "email": "test2@test.com",
      "status": "active",
      "firstName": "John",
      "lastName": "Connor",
      "role": "user",
      "permissions": {
        "userInsert": false,
        "userModify": false,
        "userRead": false,
        "postInsert": false,
        "postModify": false,
        "postRead": true
      },
      "provider": {
        "local": {
          "userId": "5e24db1d560ba309f0b0b5a8"
        }
      },
      "createdAt": "2020-01-20T20:44:44.634Z",
      "updatedAt": "2020-01-22T01:28:03.783Z"
    }
  ],
  "usersCount": 2
}

Get User

  • Method: GET
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/users/:userId
  • Response Payload
Property Name Type Description
user object User info

Sample response

{
  "user": {
    "id": "5e24d42cf7dddf012cd496b2",
    "username": "tester",
    "email": "test@test.com",
    "status": "active",
    "firstName": "Sarah",
    "lastName": "Connor",
    "role": "root",
    "permissions": {
      "userInsert": false,
      "userModify": false,
      "userRead": false,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "local": {
        "userId": "5e24d42cf7dddf012cd496b2"
      }
    },
    "createdAt": "2020-01-19T22:11:56.779Z",
    "updatedAt": "2020-01-19T23:18:47.897Z"
  }
}

Update User

  • Method: PUT
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/users/:userId
  • Resquest Body Payload
Property Name Type Required Description
role string No New role. It could be “admin” or “user”. NOTE: Only root users can update user role.
status string No New status. It could be “active”, “disabled” or “unverified-email”
permissions object No Permissions object

Sample request body payload

{
  "role": "admin",
  "permissions": {
    "userInsert": true,
    "userModify": true,
    "userRead": true,
    "postInsert": false,
    "postModify": false,
    "postRead": true
  }
}
  • Response Payload
Property Name Type Description
updatedFields string array Fields has been updated
user object Updated user info

Sample response

{
  "updatedFields": [
    "role",
    "permissions"
  ],
  "user": {
    "id": "5e24d42cf7dddf012cd496b2",
    "username": "tester",
    "email": "test@test.com",
    "status": "active",
    "firstName": "Sarah",
    "lastName": "Connor",
    "role": "admin",
    "permissions": {
      "userInsert": true,
      "userModify": true,
      "userRead": true,
      "postInsert": false,
      "postModify": false,
      "postRead": true
    },
    "provider": {
      "local": {
        "userId": "5e24d42cf7dddf012cd496b2"
      }
    },
    "createdAt": "2020-01-19T22:11:56.779Z",
    "updatedAt": "2020-01-19T23:18:47.897Z"
  }
}

Delete User

  • Method: DELETE
  • Content-Type: application/json
  • Authentication Header
Authorization: Bearer {JWT Token}
  • Endpoint
/api/users/:userId
  • Response Payload
Property Name Type Description
message string Message

Sample response

{
  "message": "User deleted."
}
-:[ 2022 ]:- If you tell the truth, you don't have to remember anything - Mark Twain