mongodb-dynamic-api 1.3.3 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 Changelog
 
+## [1.4.1](https://github.com/MikeDev75015/mongodb-dynamic-api/compare/v1.4.0...v1.4.1) (2024-03-12)
+
+## [1.4.0](https://github.com/MikeDev75015/mongodb-dynamic-api/compare/v1.3.3...v1.4.0) (2024-03-11)
+
+
+### authentication
+
+* **authentication:** add register ability predicate ([811b085](https://github.com/MikeDev75015/mongodb-dynamic-api/commit/811b0853ed836ce33a7a56312c3e045b5f73f5ee))
+
+
+### api
+
+* **api:** add authentication ([a692b7b](https://github.com/MikeDev75015/mongodb-dynamic-api/commit/a692b7b0fcd774dc5152b9f82ed22107c543110a))
+* **api:** add casl ability to control route access ([6202a24](https://github.com/MikeDev75015/mongodb-dynamic-api/commit/6202a247d301a7a72ce47f596a288d66724999f1))
+
 ## [1.3.3](https://github.com/MikeDev75015/mongodb-dynamic-api/compare/v1.3.2...v1.3.3) (2024-03-06)
 
 

package/README.md

@@ -67,6 +67,17 @@
 npm install --save mongodb-dynamic-api
 ```
 
+___
+
+### Table of Contents
+
+[Introduction](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#how-to-enjoy-it)
+- [Swagger UI](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#swagger-ui-optional-but-strongly-recommended)
+- [Validation](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#validation-optional)
+- [Versioning](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#versioning-optional)
+- [Caching](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#caching-enabled-by-default)
+- [Authentication](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#authentication-optional)
+- [Casl](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#casl-only-with-authentication)
 
 ---
 ### HOW TO ENJOY IT
@@ -85,13 +96,13 @@ npm i -S mongodb-dynamic-api
 - Add `DynamicApiModule.forRoot` to your `app.module.ts` and pass your **MongoDB connection string** to the method.
 
 ```typescript
-// app.module.ts
+// src/app.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 
 @Module({
   imports: [
     DynamicApiModule.forRoot(
-      'mongodb://127.0.0.1:27017/dynamic-api-db', // <- replace by your own connection string
+      'mongodb-uri', // <- replace by your own MongoDB connection string
     ),
     // ...
   ],
@@ -103,19 +114,19 @@ export class AppModule {}
 **Basic Usage**
 
 - Ok, now let's add our first content with just 2 files. It will be a simple `User` with a `name` and an `email` field.
-- We use the `@Schema` and `@Prop` decorators from the `@nestjs/mongoose` package to define our MongoDB model. <br>*See <strong>nestjs</strong> <a href="https://docs.nestjs.com/techniques/mongodb#model-injection" target="_blank">documentation</a> for more details.*
+- We use the `@Schema` and `@Prop` decorators from the <a href="https://docs.nestjs.com/techniques/mongodb#model-injection" target="_blank">@nestjs/mongoose</a> package to define our MongoDB model.
 
 
 - You must extend the `BaseEntity` (or `SoftDeletableEntity`) class from the `mongodb-dynamic-api` package **for all your collection models**.
 - Just create a new file `user.ts` and add the following code.
 
 ```typescript
-// users/user.ts
+// src/users/user.ts
 import { Prop, Schema } from '@nestjs/mongoose';
 import { BaseEntity } from 'mongodb-dynamic-api';
 
 @Schema({ collection: 'users' })
-export class User extends BaseEntity {
+export class User extends BaseEntity { // <- extends BaseEntity
   @Prop({ type: String, required: true })
   name: string;
 
@@ -124,12 +135,12 @@ export class User extends BaseEntity {
 }
 ```
 
-- Then we will use the `DynamicApiModule.forFeature` method to add the `User` content.
+- Then we will use the `DynamicApiModule.forFeature` method to add the `User` API to our application.
 - We pass the `User` class to the `entity` property and specify the path `users` to the `controllerOptions` property.
 - Create a new file `users.module.ts` and add the following code.
 
 ```typescript
-// users/users.module.ts
+// src/users/users.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 import { User } from './user';
 
@@ -149,7 +160,7 @@ export class UsersModule {}
 - Last step, add the `UsersModule` to the **imports** in the `app.module.ts` after the `DynamicApiModule.forRoot` method.
 
 ```typescript
-// app.module.ts
+// src/app.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 import { UsersModule } from './users/users.module';
 
@@ -183,6 +194,15 @@ export class AppModule {}
 | **POST /users/duplicate**    <br>*Duplicate many* |      `{ name?: string; email?: string; }`      |      x       | `ids: string[]` |
 | **POST /users/duplicate/:id**<br>*Duplicate one*  |      `{ name?: string; email?: string; }`      | `id: string` |        x        |
 
+___
+
+- TOC > [Validation](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#validation-optional)
+/ [Versioning](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#versioning-optional)
+/ [Caching](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#caching-enabled-by-default)
+/ [Authentication](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#authentication-optional)
+/ [Casl](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#casl-only-with-authentication)
+
+___
 
 ### [Swagger UI](https://docs.nestjs.com/openapi/introduction#document-options) (optional but strongly recommended)
 `function enableDynamicAPISwagger(app: INestApplication, options?: DynamicAPISwaggerOptions): void`
@@ -190,7 +210,7 @@ export class AppModule {}
 **Configuration**
 
 ```typescript
-// main.ts
+// src/main.ts
 import { enableDynamicAPISwagger } from 'mongodb-dynamic-api';
 
 async function bootstrap() {
@@ -212,7 +232,7 @@ Add the `@ApiProperty` | `@ApiPropertyOptional` decorators to your class propert
 <br>Let's add an optional company field to the `User` class.
 
 ```typescript
-// user.ts
+// src/users/user.ts
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 @Schema({ collection: 'users' })
@@ -235,16 +255,25 @@ go to the swagger API path (default to `/dynamic-api`) and you will see the auto
 
 ![User API](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/images/dynamic-api-user-full.Jpeg?raw=true "User API")
 
-<a href="https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/swagger.md" target="_blank">See more User API screenshots</a>
+<a href="https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/swagger-user-api.md" target="_blank">See more User API screenshots</a>
+
+___
+
+- TOC > [Introduction](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#how-to-enjoy-it)
+/ [Versioning](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#versioning-optional)
+/ [Caching](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#caching-enabled-by-default)
+/ [Authentication](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#authentication-optional)
+/ [Casl](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#casl-only-with-authentication)
 
 ___
+
 ### [Validation](https://docs.nestjs.com/techniques/validation#using-the-built-in-validationpipe) (optional)
-`function enableDynamicAPIValidation(app: INestApplication, options?: ValidationPipeOptions): void`
+<br>`function enableDynamicAPIValidation(app: INestApplication, options?: ValidationPipeOptions): void`
 
 **Configuration**
 
 ```typescript
-// main.ts
+// src/main.ts
 import { enableDynamicAPIValidation } from 'mongodb-dynamic-api';
 
 async function bootstrap() {
@@ -262,7 +291,7 @@ or in each route object defined in the routes property.
 <br>*If the options are specified in 2, the options specified in the route will have priority.*
 
 ```typescript
-// users.module.ts
+// src/users/users.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 import { User } from './user';
 
@@ -296,7 +325,7 @@ Use the `Class validator` <a href="https://github.com/typestack/class-validator?
 <br>Let's add `IsEmail` decorator to the `email` field.
 
 ```typescript
-// user.ts
+// src/users/user.ts
 import { IsEmail } from 'class-validator';
 
 @Schema({ collection: 'users' })
@@ -320,8 +349,16 @@ Ok, now if you try to create a new user with an invalid email, you will get a `4
 
 ![User API Validation](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/images/dynamic-api-validation.Jpeg?raw=true "User API Validation")
 
+___
+
+- TOC > [Introduction](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#how-to-enjoy-it)
+/ [Swagger UI](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#swagger-ui-optional-but-strongly-recommended)
+/ [Caching](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#caching-enabled-by-default)
+/ [Authentication](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#authentication-optional)
+/ [Casl](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#casl-only-with-authentication)
 
 ___
+
 ### [Versioning](https://docs.nestjs.com/techniques/versioning) (optional)
 `function enableDynamicAPIVersioning(app: INestApplication, options?: VersioningOptions): void`
 
@@ -333,7 +370,7 @@ The `enableDynamicAPIVersioning` function will automatically add versioning to t
 **Configuration**
 
 ```typescript
-// main.ts
+// src/main.ts
 import { enableDynamicAPIVersioning } from 'mongodb-dynamic-api';
 
 async function bootstrap() {
@@ -353,7 +390,7 @@ Pass the `version` property to the `controllerOptions` object or to the `route`
 Let's add a new version to the `User` content.
 
 ```typescript
-// create-one-user-v2.dto.ts
+// src/users/create-one-user-v2.dto.ts
 import { ApiProperty, ApiPropertyOptional, PickType } from '@nestjs/swagger';
 import { IsOptional, IsString } from 'class-validator';
 import { User } from './user';
@@ -375,7 +412,7 @@ export class CreateOneUserV2Dto extends PickType(User, ['email']) {
 ```
 
 ```typescript
-// user-v2.presenter.ts
+// src/users/user-v2.presenter.ts
 import { ApiProperty, ApiPropertyOptional, PickType } from '@nestjs/swagger';
 import { User } from './user';
 
@@ -392,7 +429,7 @@ export class UserV2Presenter extends PickType(User, ['email']) {
 ```
 
 ```typescript
-// users.module.ts
+// src/users/users.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 import { User } from './user';
 import { CreateOneUserV2Dto } from './create-one-user-v2.dto';
@@ -428,6 +465,13 @@ Great, now you have a versioned User API, and you can access it at the `/v1/user
 
 ![User API Versioned](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/images/dynamic-api-versioning.Jpeg?raw=true "User API Versioned")
 
+___
+
+- TOC > [Introduction](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#how-to-enjoy-it)
+/ [Swagger UI](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#swagger-ui-optional-but-strongly-recommended)
+/ [Validation](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#validation-optional)
+/ [Authentication](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#authentication-optional)
+/ [Casl](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#casl-only-with-authentication)
 
 ___
 
@@ -439,7 +483,7 @@ By default, the caching is activated globally for all the routes. It uses the ne
 **Configuration**
 
 ```typescript
-// app.module.ts
+// src/app.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 
 @Module({
@@ -463,7 +507,7 @@ export class AppModule {}
 **[Not recommended]** The cache can also be disabled globally with the `useGlobalCache` property set to `false` in the `DynamicApiModule.forRoot` method.
 
 ```typescript
-// app.module.ts
+// src/app.module.ts
 import { DynamicApiModule } from 'mongodb-dynamic-api';
 
 @Module({
@@ -505,6 +549,417 @@ When you request the `/users` route with the `GET` method, the response will be
 ```
 ![Third GET request](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/images/dynamic-api-caching-4-GET-third-request.Jpeg?raw=true "Third GET request")
 
+___
+
+- TOC > [Introduction](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#how-to-enjoy-it)
+/ [Swagger UI](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#swagger-ui-optional-but-strongly-recommended)
+/ [Validation](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#validation-optional)
+/ [Versioning](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#versioning-optional)
+/ [Casl](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#casl-only-with-authentication)
+
+___
+
+### [Authentication](https://docs.nestjs.com/security/authorization#integrating-casl) (optional)
+
+An authentication strategy like <a href="https://docs.nestjs.com/security/authentication#jwt-token" target="_blank">JWT</a> is already implemented in the Dynamic API.
+All you have to do is to pass the User object and some options to the `useAuth` property of the `DynamicApiModule.forRoot` method.
+
+**Configuration**
+
+Ok, let's update our `User` class to add a `password` field.
+
+```typescript
+// src/users/user.ts
+import { IsEmail } from 'class-validator';
+
+@Schema({ collection: 'users' })
+export class User extends BaseEntity {
+  @ApiProperty()
+  @IsNotEmpty()
+  @IsString()
+  @Prop({ type: String, required: true })
+  email: string;
+
+  @Exclude()
+  @IsNotEmpty()
+  @IsString()
+  @Prop({ type: String, required: true })
+  password: string;
+
+  @ApiPropertyOptional({ type: Boolean, default: false })
+  @IsBoolean()
+  @IsOptional()
+  @Prop({ type: Boolean, default: false })
+  isAdmin: boolean;
+
+  @ApiPropertyOptional()
+  @IsNotEmpty()
+  @IsString()
+  @IsOptional()
+  @Prop({ type: String })
+  company?: string;
+}
+```
+
+Now, we are going to add the `useAuth` property to the `DynamicApiModule.forRoot` method and pass the `User` object and some options.
+<br>By default, the login field is `email` and the password field is `password`. Your User class must have these fields.
+<br>If you want to use other fields, you can specify them in the `user` property by passing the `loginField` and / or `passwordField` properties.
+
+```typescript
+// src/app.module.ts
+import { DynamicApiModule } from 'mongodb-dynamic-api';
+import { User } from './users/user';
+import { UsersModule } from './users/users.module';
+
+@Module({
+  imports: [
+    DynamicApiModule.forRoot('...', {
+      // ...,
+      useAuth: { // <- add this
+        user: {
+          entity: User, // <- put here the entity which will represent a User of your API
+        },
+      },
+    }),
+    UsersModule,
+  ],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}
+```
+
+By setting the `useAuth` property, the Dynamic API will automatically add the authentication API.
+<br>It will add the `/auth/register`, `/auth/login`, and `/auth/account` routes to the API.
+
+By default, only the `/auth/register` and `/auth/login` routes are public.
+All other routes are protected and require a valid `JWT token` to access them.
+
+**Swagger Configuration**
+
+For Swagger users, you must enable the bearer Auth option by setting the `bearerAuth` property to `true` in the enableDynamicAPISwagger method.
+This will add the Authorize button in the Swagger UI. This button will allow you to pass the `JWT Token` and unlock the protected routes.
+
+```typescript
+// src/main.ts
+import { enableDynamicAPISwagger } from 'mongodb-dynamic-api';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  // ...
+  enableDynamicAPISwagger(app, {
+    // ...,
+    swaggerExtraConfig: { // <- add this line in your main.ts file
+      bearerAuth: true,
+    },
+  });
+
+  await app.listen(3000);
+}
+```
+
+![Swagger UI - Authentication API](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/images/dynamic-api-authentication.Jpeg?raw=true "Swagger UI - Authentication API")
+
+<a href="https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README/swagger-authentication-api.md" target="_blank">See more Authentication API screenshots</a>
+
+
+**Usage**
+
+Ok let's add a new user with the `POST` method on the `/auth/register` route.
+<br>You will receive a valid `JWT token` in the response.
+
+```text
+POST /auth/register
+
+curl -X 'POST' \
+  '<your-host>/auth/register' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "email": "<your-email>",
+  "password": "<your-password>" // <- the password will be hashed automatically before saving in the database
+}'
+```
+```json
+# Server response
+{"accessToken":"<your-jwt-token>"}
+```
+
+If you go to `/auth/login` and request the route with the `POST` method passing the `email` and `password` fields in the body.
+<br>You will also receive a valid `JWT token` in the response.
+
+```text
+POST /auth/login
+
+curl -X 'POST' \
+  '<your-host>/auth/login' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "email": "<your-email>",
+  "password": "<your-password>"
+}'
+```
+```json
+# Server response
+{"accessToken":"<your-jwt-token>"}
+```
+
+Now let's request the `/auth/account` protected route with the `GET` method and pass our valid JWT token in the `Authorization` header.
+
+```text
+GET /auth/account
+
+curl -X 'GET' \
+  '<your-host>/auth/account' \
+  -H 'accept: application/json' \
+  -H 'Authorization: Bearer <your-jwt-token>'
+```
+```json
+# Server response
+{"id":"65edc717c1ec...","email":"<your-email>"}
+```
+
+Great, now you have a fully functional authentication API.
+
+All other routes are protected and require a valid JWT token to be accessed. You can easily make it public by adding the `isPublic` property to the `controllerOptions` object or to the `route` object in the `DynamicApiModule.forFeature` method.
+    
+```typescript
+// src/users/users.module.ts
+import { DynamicApiModule } from 'mongodb-dynamic-api';
+import { User } from './user';
+
+@Module({
+  imports: [
+    DynamicApiModule.forFeature({
+      entity: User,
+      controllerOptions: {
+        path: 'users',
+        isPublic: true, // <- add this to make all user API routes public
+      },
+      // ...
+    }),
+  ],
+})
+export class UsersModule {}
+```
+```typescript
+// src/users/users.module.ts
+import { DynamicApiModule } from 'mongodb-dynamic-api';
+import { User } from './user';
+
+@Module({
+  imports: [
+    DynamicApiModule.forFeature({
+      entity: User,
+      controllerOptions: {
+        path: 'users',
+      },
+      routes: [
+        { type: 'GetMany' }, // <- protected route
+        { type: 'GetOne', isPublic: true }, // <- public route
+        { type: 'UpdateOne' }, // <- protected route
+        { type: 'DeleteOne' }, // <- protected route
+      ],
+    }),
+  ],
+})
+export class UsersModule {}
+```
+
+___
+
+- TOC > [Introduction](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#how-to-enjoy-it)
+/ [Swagger UI](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#swagger-ui-optional-but-strongly-recommended)
+/ [Validation](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#validation-optional)
+/ [Versioning](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#versioning-optional)
+/ [Caching](https://github.com/MikeDev75015/mongodb-dynamic-api/blob/develop/README.md#caching-enabled-by-default)
+
+___
+
+### [Casl](https://docs.nestjs.com/security/authorization#integrating-casl) (only with authentication)
+
+Casl will allow you to condition the actions of your users for each protected route of your APIs.
+<br>Authentication is required, you need to enable it or implement your own strategy that adds the User object in the request.
+
+**MongoDB dynamic API** uses the `User` object in the requests to apply the ability predicates defined in the `DynamicApiModule.forFeature`.
+<br>You can define them either **in the controller options**,
+or **in each route object** declared in the routes property.
+<br>*If the ability predicates are specified in 2, those defined in the route will have priority.*
+
+**An ability predicate is an arrow function that takes a subject and the User object (optional) as arguments and returns a boolean.**
+
+Let's create a new Article content and set the ability predicates to the `UpdateOne`, `DeleteOne` and `DeleteMany` routes.
+
+**Configuration**
+
+```typescript
+// src/articles/article.ts
+import { Prop } from '@nestjs/mongoose';
+import { ApiProperty } from '@nestjs/swagger';
+import { BaseEntity } from 'mongodb-dynamic-api';
+
+export class Article extends BaseEntity {
+  @ApiProperty({ type: Boolean, default: false })
+  @Prop({ type: Boolean, default: false })
+  isPublished: boolean;
+
+  @ApiProperty()
+  @Prop({ type: String })
+  authorId: string;
+}
+```
+
+```typescript
+// src/articles/articles.module.ts
+import { Module } from '@nestjs/common';
+import { DynamicApiModule } from 'mongodb-dynamic-api';
+import { User } from '../users/user';
+import { Article } from './article';
+
+@Module({
+  imports: [
+    DynamicApiModule.forFeature({
+      entity: Article,
+      controllerOptions: {
+        path: 'articles',
+        abilityPredicates: [ // <- declare the ability predicates in the controller options
+          {
+            targets: ['DeleteMany', 'DeleteOne'], // <- declare the targets
+            predicate: (_: Article, user: User) => user.isAdmin, // <- add the condition
+          },
+        ],
+      },
+      routes: [
+        { type: 'GetMany', isPublic: true },
+        { type: 'GetOne', isPublic: true },
+        { type: 'CreateOne' },
+        {
+          type: 'UpdateOne',
+          abilityPredicate: (article: Article, user: User) => // <- declare the ability predicate in the route object
+            article.authorId === user.id && !article.isPublished,
+        },
+      ],
+    }),
+  ],
+})
+export class ArticlesModule {}
+```
+
+```typescript
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { DynamicApiModule } from 'mongodb-dynamic-api';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { User } from './users/user';
+import { ArticlesModule } from './articles/articles.module';
+
+@Module({
+  imports: [
+    DynamicApiModule.forRoot(
+      'your-mongodb-uri',
+      {
+        useAuth: {
+          user: {
+            entity: User,
+            additionalFields: {
+              toRegister: ['isAdmin'], // <- here you can set additional fields to display in the register body
+              toRequest: ['isAdmin', 'company'], // <- here you can set additional fields to the User object in the request
+            },
+          },
+        },
+      },
+    ),
+    ArticlesModule,
+  ],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}
+```
+
+
+**Usage**
+
+First, let's create an admin user with the `POST` method on the `/auth/register` public route.
+```text
+POST /auth/register
+
+curl -X 'POST' \
+  '<your-host>/auth/register' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "email": "admin@test.co",
+  "isAdmin": true,
+  "password": "admin"
+}'
+```
+
+Then, we are going to protect the `/auth/register` route by setting the `protectRegister` property to `true` and add a **register ability predicate** in the useAuth Object of the `DynamicApiModule.forRoot` method.
+```typescript
+// src/app.module.ts
+@Module({
+  imports: [
+    DynamicApiModule.forRoot(
+      'your-mongodb-uri',
+      {
+        useAuth: {
+          // ...,
+          protectRegister: true, // <- add this line
+          registerAbilityPredicate: (user: User) => user.isAdmin,
+        },
+      },
+    ),
+```
+
+Ok, now let's create a non admin user with the `POST` method on the `/auth/register` route.
+```text
+POST /auth/register
+
+curl -X 'POST' \
+  '<your-host>/auth/register' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "email": "toto@test.co",
+  "password": "toto"
+}'
+```
+```json
+# Server response
+{"accessToken":"<toto-jwt-token>"}
+```
+
+Next, under toto's account (not admin), we will try to register a new user with the `POST` method on the `/auth/register` route.
+<br>The register ability predicate will return `false` and we will receive a `403 Forbidden` error.
+
+```text
+POST /auth/register
+
+curl -X 'POST' \
+  'http://localhost:5000/auth/register' \
+  -H 'accept: application/json' \
+  -H 'Authorization: Bearer <toto-jwt-token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "email": "bill@test.co",
+  "password": "bill"
+}'
+```
+```json
+# Server response
+{
+  "message": "Forbidden resource",
+  "error": "Forbidden",
+  "statusCode": 403
+}
+```
+
+The register route is now well protected and only an admin user can create new users.
+
+
 ___
 
 More coming soon...