Mua-Backend Documentation and Integration Guide

The mua-backend is a full authentication and user management system designed to integrate seamlessly with the mua-frontend. It enables a Slack-like authentication experience, supporting multiple workspaces where users can log in with shared or separate credentials per workspace.

This backend simplifies the creation and management of accounts, users, and system administrators, providing ready-to-use routes.

Features

• Slack-like Workspace Management: Users can log into separate workspaces, each with its own independent credentials.
• Route Auto-Generation: Automatically generates routes for account, user, and system admin management.
• Flexible API Integration: Built to work with an API server created using the Express Async API.

Getting Started

Installation

Install mua-backend via npm:

npm install mua-backend

Setup

To set up the mua-backend, you need to provide the following parameters:

1. API Server

• An instance created using the express-async-api library.

2. Models

• To ensure smooth integration and customization, it's essential that you pass the following models to the mua-backend. These models define the mandatory properties that are needed for managing accounts, users, and system administrators. You can extend these models by adding additional properties as needed.

• AccountModel: The model for managing workspace accounts.

const AccountSchema = new mongoose.Schema({
  name: { type: String },
  urlFriendlyName: { type: String, unique: true },
  logo: { type: String },
  deleted: { type: Boolean }
}, { timestamps: true })

export default mongoose.model('Account', AccountSchema)

• UserModel: The model for managing users.

const UserSchema = new mongoose.Schema({
  name: { type: String },
  email: { type: String, lowercase: true, required: true, match: /.+[\\@].+\..+/ },
  password: { type: String },
  googleProfileId: { type: String },
  microsoftProfileId: { type: String },
  githubProfileId: { type: String },
  role: { type: String, default: 'user', enum: ['user', 'admin'] },
  accountId: { type: Schema.Types.ObjectId, ref: 'Account', required: true },
  profilePicture: { type: String },
  verified: { type: Boolean, default: false },
  deleted: { type: Boolean }
}, { timestamps: true })

export default mongoose.model('User', UserSchema)

• SystemAdminModel: The model for managing system administrators.

const SystemAdminSchema = new mongoose.Schema({
  name: { type: String },
  email: { type: String, lowercase: true, required: true, match: /.+[\\@].+\..+/, unique: true },
  password: { type: String },
  profilePicture: { type: String }
}, { timestamps: true });

export default mongoose.model('SystemAdmin', SystemAdminSchema)

3. Integration Example

import MuaBackend from'mua-backend' 
import AccountModel from'./models/account' 
import UserModel from'./models/user'
import SystemAdminModel from'./models/systemAdmin' 

MuaBackend({  
  apiServer,  
  AccountModel,
  UserModel,
  SystemAdminModel,
  hooks: {} // optional  
})

4. Add to .env file

You need to provide the following environment variables in a .env file for Mua to function properly.

NODE_ENV=development # Environment mode (e.g., development, production)
SECRETS=testsecret1 testsecret2 # Space-separated list of secrets used for token encryption

APP_URL=<app_url> # The base URL of your application

BLUEFOX_TRANSACTIONAL_EMAIL_API_URL=<emailfox_transactional_url> # URL for the Bluefox transactional email API
BLUEFOX_API_KEY=<bluefox_email_api_key> # API key for Bluefox email service

BLUEFOX_TEMPLATE_ID_ADMIN_VERIFY_EMAIL=<bluefox_template_id> # Bluefox Template ID for admin email verification
BLUEFOX_TEMPLATE_ID_ADMIN_FORGOT_PASSWORD=<bluefox_template_id> # Bluefox Template ID for admin forgot password
BLUEFOX_TEMPLATE_ID_ADMIN_INVITATION=<bluefox_template_id> # Bluefox Template ID for admin invitation
BLUEFOX_TEMPLATE_ID_ACCOUNT_FINALIZE_REGISTRATION=<bluefox_template_id> # Bluefox Template ID for account registration finalization
BLUEFOX_TEMPLATE_ID_ACCOUNT_FORGOT_PASSWORD=<bluefox_template_id> # Bluefox Template ID for account forgot password
BLUEFOX_TEMPLATE_ID_ACCOUNT_INVITATION=<bluefox_template_id> # Bluefox Template ID for account invitation
BLUEFOX_TEMPLATE_ID_ACCOUNT_LOGIN_SELECT=<bluefox_template_id> # Bluefox Template ID for account login selection
BLUEFOX_TEMPLATE_ID_ACCOUNT_VERIFY_EMAIL=<bluefox_template_id> # Bluefox Template ID for account email verification
BLUEFOX_TEMPLATE_ID_ACCOUNT_CREATE_PASSWORD=<bluefox_template_id> # Bluefox Template ID for account password creation

CDN_BASE_URL=<cdn_base_url> # Base URL for your CDN

AWS_BUCKET_PATH=<aws.bucket.path> # Path to the AWS bucket
AWS_BUCKET_NAME=<your_aws_bucket_name> # Name of the AWS S3 bucket
AWS_FOLDER_NAME=<your_aws_folder_name> # Folder name in the AWS S3 bucket
AWS_REGION=<your_aws_region> # AWS region for the S3 bucket
AWS_ACCESS_KEY_ID=<your_aws_access_key_id> # AWS access key ID
AWS_SECRET_ACCESS_KEY=<your_aws_secret_access_key> # AWS secret access key

ALPHA_MODE=false # Enable alpha mode (true/false)
MAX_FILE_SIZE=5242880 # Maximum file upload size in bytes (e.g., 5MB)

GOOGLE_CLIENT_ID=<your_google_client_id> # Google OAuth client ID
GOOGLE_CLIENT_SECRET=<your_google_client_secret> # Google OAuth client secret

MICROSOFT_CLIENT_ID=<your_microsoft_client_id> # Microsoft OAuth client ID
MICROSOFT_CLIENT_SECRET=<your_microsoft_client_secret> # Microsoft OAuth client secret

GITHUB_CLIENT_ID=<your_github_client_id> # GitHub OAuth client ID
GITHUB_CLIENT_SECRET=<your_github_client_secret> # GitHub OAuth client secret

Customization

The mua-backend allows users to customize behavior after specific actions, such as creating or deleting accounts. Pass a hooks object with functions to override default behaviors:

MuaBackend({
  apiServer,
  AccountModel,
  UserModel,
  SystemAdminModel,
  hooks: {
    deleteAccount: {
      post: (params) => {
        // Custom logic after deleting an account
      },
    },
    createAccount: {
      post: (params) => {
        // Custom logic after creating an account
      },
    },
    createNewUser: {
      post: (params) => {
        // Custom logic after creating a new user
      },
    },
    updateUserEmail: {
      post: (params) => {
        // Custom logic after updating a user's email
      },
    },
  },
})

Each hook accepts an object with a post method that executes custom logic after the associated action is completed.

API Routes

Developers using mua can rely on the seamless integration with the mua-frontend, so they don't need to concern themselves with these routes. The table below outlines the automatically generated routes and their purposes:

Accounts routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/accounts/create | POST | Create an account. | | /v1/accounts/ | POST | Create a new account by admin. | | /v1/accounts/:id/logo | POST | Upload account logo. | | /v1/accounts/permission/:permissionFor | POST | Assign permission to an account. | | /v1/accounts/ | GET | Retrieve all accounts. | | /v1/accounts/:id | GET | Retrieve account by ID. | | /v1/accounts/by-url-friendly-name/:urlFriendlyName | GET | Retrieve account by URL-friendly name. | | /v1/accounts/check-availability | GET | Check if account is available pass urlFriendlyName in query. | | /v1/accounts/:id/name | PATCH | Update account name. | | /v1/accounts/:id/urlFriendlyName | PATCH | Update account URL-friendly name. | | /v1/accounts/:id/logo | DELETE | Delete account logo. | | /v1/accounts/:id | DELETE | Delete an account. |

System admins routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/system-admins/permission/:permissionFor | POST | Assign permission to a system admin. | | /v1/system-admins/:id/profile-picture | POST | Upload system admin profile picture. | | /v1/system-admins/ | GET | Retrieve all system admins. | | /v1/system-admins/:id | GET | Retrieve system admin by ID. | | /v1/system-admins/:id/access-token | GET | Retrieve access token for a system admin. | | /v1/system-admins/:id/name | PATCH | Update system admin name. | | /v1/system-admins/:id/password | PATCH | Update system admin password. | | /v1/system-admins/:id/email | PATCH | Update system admin email. | | /v1/system-admins/:id/email-confirm | PATCH | Confirm system admin email. | | /v1/system-admins/:id/profile-picture | DELETE | Delete system admin profile picture. | | /v1/system-admins/:id | DELETE | Delete a system admin. |

Users routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/accounts/:accountId/users | POST | Create a new user in account. | | /v1/accounts/:accountId/users/:id/profile-picture | POST | Upload user profile picture. | | /v1/accounts/:accountId/users | GET | Retrieve all users in account. | | /v1/accounts/:accountId/users/:id | GET | Retrieve user by ID in account. | | /v1/accounts/:accountId/users/:id/name | PATCH | Update user name in account. | | /v1/accounts/:accountId/users/:id/password | PATCH | Update user password. | | /v1/accounts/:accountId/users/:id/email | PATCH | Update user email. | | /v1/accounts/:accountId/users/:id/create-password | PATCH | Create password for user. | | /v1/accounts/:accountId/users/:id/email-confirm | PATCH | Confirm user email. | | /v1/accounts/:accountId/users/:id/profile-picture | DELETE | Delete user profile picture. | | /v1/accounts/:accountId/users/:id | DELETE | Delete a user in account. |

Auth routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/accounts/:id/login | POST | Log in to an account. | | /v1/accounts/:id/login/url-friendly-name | POST | Log in using URL-friendly name. | | /v1/accounts/login | POST | Log in to any account. | | /v1/system-admins/login | POST | Log in as system admin. | | /v1/accounts/:accountId/users/:id/finalize-registration | POST | Finalize user registration in account. | | /v1/accounts/:accountId/users/:userId/resend-finalize-registration | POST | Resend finalize registration for a user. | | /v1/accounts/:accountId/users/:id/access-token | GET | Retrieve user access token in account. |

Provider Auth routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/accounts/:accountId/users/:id/link/provider/:provider | POST | Link user to a provider (e.g., Google). | | /v1/accounts/create-account/provider/:provider | POST | Create an account via third-party provider. | | /v1/accounts/:id/login/provider/:provider | POST | Log in via third-party provider (e.g., Google). | | /v1/accounts/provider/google/callback | GET | Google OAuth callback. | | /v1/accounts/provider/microsoft/callback | GET | Microsoft OAuth callback. | | /v1/accounts/provider/github/callback | GET | GitHub OAuth callback. | | /v1/accounts/:accountId/users/:id/provider/:provider | PATCH | Update user provider link. |

Forgot password routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/accounts/:id/forgot-password/send | POST | Send password reset email for account. | | /v1/system-admins/forgot-password/send | POST | Send password reset email for system admin. | | /v1/accounts/:id/forgot-password/reset | POST | Reset account password. | | /v1/system-admins/forgot-password/reset | POST | Reset system admin password. |

Invitation routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/accounts/:id/invitation/send | POST | Send invitation for account. | | /v1/system-admins/invitation/send | POST | Send invitation for system admin. | | /v1/accounts/:id/invitation/resend | POST | Resend account invitation. | | /v1/system-admins/invitation/resend | POST | Resend system admin invitation. | | /v1/accounts/:id/invitation/accept | POST | Accept account invitation. | | /v1/system-admins/invitation/accept | POST | Accept system admin invitation. |

Statistics routes

| Route | Method | Description | |-------------------------------------------------------------|---------|-------------------------------------------------------| | /v1/statistics/accounts/ | GET | Retrieve statistics for accounts. | | /v1/statistics/users/ | GET | Retrieve statistics for users. |