changes from review

Author: claurospace

docs/book/v4/core-features/authentication.md

@@ -3,79 +3,79 @@
 Authentication is the process by which an identity is presented to the application. It ensures that the entity
 making the request has the proper credentials to access the API.
 
-DotKernel's API identities are delivered to the application from the client through the `Authorization` request
-header.  If it is present, the application tries to find and assign the identity to the application. If it is not presented,
-DotKernel's API assigns a default `guest` identity, represented by an instance of the class
+DotKernel API identities are delivered to the application from the client through the `Authorization` request
+If it is present, the application tries to find and assign the identity to the application. If it is not presented,
+DotKernel API assigns a default `guest` identity, represented by an instance of the class
 `Mezzio\Authentication\UserInterface`.
 
 ## Configuration
 
-DotKernel's API authentication is made around `mezzio/mezzio-authentication-oauth2` component and is already configured.
-with what is necessary in order to work. But if you want to dig more, the configuration is hold on.
-`config/autoload/local.php` under the authentication key.
+Authentication in DotKernel API is built around `mezzio/mezzio-authentication-oauth2` component and is already configured
+with what is necessary in order to work. But if you want to dig more, the configuration is stored in
+`config/autoload/local.php` under the `authentication` key.
 
 > You can check the [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)
-> configuration part for more digging.
+> configuration part for more info.
 
 ## How it works
 
-DotKernel's API authentication system can be used for SPAs (single-page applications), mobile applications, and
+DotKernels API authentication system can be used for SPAs (single-page applications), mobile applications, and
 simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts.
 
 The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
 
 ## Database
 
 When DotKernel API is installed for the first time, and you run the migrations and seeders, all the tables
-needed for authentication are automatically created and inserted with the data needed for authentication.
+needed for authentication are automatically created and populated with the data needed for authentication.
 
-In DotKernel's API, authentication users can be from the `admin` table and from the `users` table. We choose to keep the admin
+In DotKernel API, authenticated users come from either the `admin` or the `users` table. We choose to keep the admin
 table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators
 of the application should access.
 
 Knowing this, upon migrations, the `oauth_clients` table is pre-populated with the default `admin` and `frontend` clients with
-the same password as their names. (you can change those passwords.).
+the same password as their names (you can change those passwords).
 
-As you guested each client serves to authenticate `admin` or `users`.
+As you guessed each client serves to authenticate `admin` or `users`.
 
 Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
 
 ### Issuing API Tokens
 
-In DotKernel's API, generating tokens is done using the `password` `grand_type` scenario, which in this case allows authentication
+Token generation in DotKernel API is done using the `password` `grand_type` scenario, which in this case allows authentication
 to an API using the user's credentials (generally a username and password).
 
 The client sends a POST request to the `/security/generate-token` with the following parameters:
 
 - `grant_type` = password.
-- `client_id` with the client name (from `oauth_clients` table).
-- `client_secret` with the client secret (password from `oauth_clients` table for the client).
-- `scope` with the scope from `oauth_scopes` table.
-- `username` with the user’s username.
-- `password` with the user’s password.
+- `client_id` = column `name` from the `oauth_clients` table
+- `client_secret` = column `secret` from the `oauth_clients` table
+- `scope` = column `scope` from the `oauth_scopes` table
+- `username` = column `identity` from table `admin`/`user`
+- `password` = column `password` from table `admin`/`user`
 
 ```shell
 POST /security/generate-token HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 {
-"grant_type": "password",
-"client_id": "frontend",
-"client_secret": "frontend",
-"scope": "api",
-"username": "test@dotkernel.com",
-"password": "dotkernel"
+  "grant_type": "password",
+  "client_id": "frontend",
+  "client_secret": "frontend",
+  "scope": "api",
+  "username": "test@dotkernel.com",
+  "password": "dotkernel"
 }
 ```
 
 The server responds with a JSON as follows:
 
-```php
+```json
 {
-"token_type": "Bearer",
-"expires_in": 86400,
-"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
-"refresh_token": "def5020087199939a49d0f2f818..."
+    "token_type": "Bearer",
+    "expires_in": 86400,
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+    "refresh_token": "def5020087199939a49d0f2f818..."
 }
 ```
 
@@ -90,7 +90,7 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
 
 ### Refreshing tokens
 
-DotKernel's API provides the ability to refresh the access token, generating a new one.
+DotKernel API provides the ability to refresh the access token, by generating a new one using the expired access token's `refresh_token`.
 
 The clients need to send a `POST` request to the `/security/refresh-token` with the following request
 
@@ -99,21 +99,21 @@ POST /security/refresh-token HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 {
-"grant_type": "refresh_token",
-"client_id": "frontend",
-"client_secret": "frontend",
-"scope": "api",
-"refresh_token" : "def5020087199939a49d0f2f818..."
+  "grant_type": "refresh_token",
+  "client_id": "frontend",
+  "client_secret": "frontend",
+  "scope": "api",
+  "refresh_token" : "def5020087199939a49d0f2f818..."
 }
 ```
 
 The server responds with a JSON as follows:
 
-```php
+```json
 {
-"token_type": "Bearer",
-"expires_in": 86400,
-"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
-"refresh_token": "def5020087199939a49d0f2f818..."
+  "token_type": "Bearer",
+  "expires_in": 86400,
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+  "refresh_token": "def5020087199939a49d0f2f818..."
 }
 ```

docs/book/v4/core-features/authorization.md

@@ -3,74 +3,74 @@
 Authorization is the process by which a system take a validated identity and checks if that identity has access to a
 given resource.
 
-DotKernel's APIs implementation of the authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of
-Role-Based Access Control (RBAC)
+DotKernel APIs implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of
+Role-Based Access Control (RBAC).
 
 ## How it works
 
-In DotKernel's API each authenticatable entity (admin and users) comes in with their roles table where you can define
+In DotKernel API each authenticatable entity (admin/user) comes with their roles table where you can define
 roles for each entity. RBAC comes in to ensure that each entity has the appropriate role and permission to access a resource.
 
-The authorization happens through the middleware in the `Api\App\Middleware\AuthorizationMiddleware`.
+The authorization happens through the `Api\App\Middleware\AuthorizationMiddleware` middleware.
 
 ## Configuration
 
-In DotKernel API make use of `mezzio-authorization-rbac` and upon installation all the configuration is already made
+DotKernel API makes use of `mezzio-authorization-rbac` and upon installation all the configuration is already made
 in order for the authorization to work.
 
-The configuration where you define roles and permission is hold on `config/autoload/authorization.global.php`
+The configuration file for the role and permission definitions is `config/autoload/authorization.global.php`.
 
 ```php
 'mezzio-authorization-rbac' => [
-        'roles'       => [
-            AdminRole::ROLE_SUPERUSER => [],
-            AdminRole::ROLE_ADMIN     => [
-                AdminRole::ROLE_SUPERUSER,
-            ],
-            UserRole::ROLE_GUEST      => [
-                UserRole::ROLE_USER,
-            ],
+    'roles'       => [
+        AdminRole::ROLE_SUPERUSER => [],
+        AdminRole::ROLE_ADMIN     => [
+            AdminRole::ROLE_SUPERUSER,
         ],
-        'permissions' => [
-            AdminRole::ROLE_SUPERUSER => [],
-            AdminRole::ROLE_ADMIN     => [
-                'other.routes'
-                'admin.list',
-                'home'
-            ],
-            UserRole::ROLE_USER       => [
-                'other.routes',
-                'user.my-account.update',
-                'user.my-account.view',
-            ],
-            UserRole::ROLE_GUEST      => [
-                'other.routes',
-                'security.refresh-token',
-                'error.report',
-                'home',
-            ],
+        UserRole::ROLE_GUEST      => [
+            UserRole::ROLE_USER,
         ],
     ],
+    'permissions' => [
+        AdminRole::ROLE_SUPERUSER => [],
+        AdminRole::ROLE_ADMIN     => [
+            'other.routes'
+            'admin.list',
+            'home'
+        ],
+        UserRole::ROLE_USER       => [
+            'other.routes',
+            'user.my-account.update',
+            'user.my-account.view',
+        ],
+        UserRole::ROLE_GUEST      => [
+            'other.routes',
+            'security.refresh-token',
+            'error.report',
+            'home',
+        ],
+    ],
+],
 ```
 
-> You can check [mezzio-authorization-rbac](https://docs.mezzio.dev/mezzio-authorization-rbac/v1/basic-usage/) for more
-> in depth
+>  See [mezzio-authorization-rbac](https://docs.mezzio.dev/mezzio-authorization-rbac/v1/basic-usage/)
+> for more information.
 
 ## Usage
 
 Based on the configuration file above, we have 2 admins roles (`superuser`, `admin`) and 2 users roles (`user`, `guest`).
 
-A role can inherit the roles of their parent:
+Roles inherit the permissions from their parents:
 
 - `superuser` has no parent
 - `admin` has `superuser` as a parent which means `superuser` will inherit `admin` permissions
 - `user` has no parent
 - `guest` has `user` as a parent which means `user` will inherit `guest` permissions
 
-For each role we defined an array of permissions. A permission in DotKernel's is basically a route name.
+For each role we defined an array of permissions. A permission in DotKernel API is basically a route name.
 
-As you can see, the `superuser` does not have any permission, because inherit all the permission from `admin`no
-need to define permission for him again.
+As you can see, the `superuser` does not have it's own permissions, because it inherits all the permissions from `admin`,
+no need to define permissions for it unless necessary.
 
-The `user` role, inherit all the permission from `guest` so no need to define that `user` can access `home` route, but
-`guest` cannot access `user.my-account.view` route.
+The `user` role, inherits all the permission from `guest` so no need to define that `user` can access `home` route, but
+`guest` cannot access user-specific routes.