gains

Author: arhimede

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

@@ -3,15 +3,15 @@
 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 API** identities are delivered to the application from the client through the `Authorization` request
+**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
 
-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
+Authentication in DotKernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already
+configured out of the box. But if you want to dig more, the configuration is stored in
 `config/autoload/local.php` under the `authentication` key.
 
 > You can check the
@@ -27,17 +27,17 @@ The authentication happens through the middleware in the `Api\App\Middleware\Aut
 
 ## 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 populated with the data needed for authentication.
+When you install **DotKernel API** for the first time, you need to run the migrations and seeders. All the tables
+required for authentication are automatically created and populated.
 
-In DotKernel API, authenticated users come from either the `admin` or the `users` table. We choose to keep the admin
+In DotKernel API, authenticated users come from either the `admin` or the `user` 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 `oauth_clients` table is pre-populated with the default `admin` and `frontend` clients with the same password as
+their names (**we recommend you change the default passwords**).
 
-As you guessed each client serves to authenticate `admin` or `users`.
+As you guessed each client serves to authenticate `admin` or `user`.
 
 Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
 
@@ -91,8 +91,7 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
 
 ### Refreshing tokens
 
-DotKernel API provides the ability to refresh the access token, by generating a new one using the expired access
-token's `refresh_token`.
+DotKernel API can refresh the access token, based on the expired access token's `refresh_token`.
 
 The clients need to send a `POST` request to the `/security/refresh-token` with the following request
 

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

@@ -1,9 +1,9 @@
 # Authorization
 
-Authorization is the process by which a system take a validated identity and checks if that identity has access to a
+Authorization is the process by which a system takes a validated identity and checks if that identity has access to a
 given resource.
 
-DotKernel APIs implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of
+**DotKernel API**'s implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of
 Role-Based Access Control (RBAC).
 
 ## How it works
@@ -16,8 +16,7 @@ The authorization happens through the `Api\App\Middleware\AuthorizationMiddlewar
 
 ## Configuration
 
-DotKernel API makes use of `mezzio-authorization-rbac` and upon installation all the configuration is already made
-in order for the authorization to work.
+DotKernel API makes use of `mezzio-authorization-rbac` and includes the full configuration.
 
 The configuration file for the role and permission definitions is `config/autoload/authorization.global.php`.
 
@@ -65,15 +64,14 @@ roles (`user`, `guest`).
 Roles inherit the permissions from their parents:
 
 - `superuser` has no parent
-- `admin` has `superuser` as a parent which means `superuser` will inherit `admin` permissions
+- `admin` has `superuser` as a parent which means `superuser` also has `admin` permissions
 - `user` has no parent
-- `guest` has `user` as a parent which means `user` will inherit `guest` permissions
+- `guest` has `user` as a parent which means `user` also has `guest` permissions
 
 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 its own permissions, because it inherits all the permissions
-from `admin`,
-no need to define permissions for it unless necessary.
+As you can see, the `superuser` does not have its own permissions, because it gains all the permissions
+from `admin`, no need to define explicit permissions.
 
-The `user` role, inherits all the permission from `guest` so no need to define that `user` can access `home` route, but
+The `user` role, gains all the permission from `guest` so no need to define that `user` can access `home` route, but
 `guest` cannot access user-specific routes.

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

@@ -79,9 +79,9 @@ This list explains the above configuration values:
 
 - `allowed_origins`: an array of domains that are allowed to interact with the API
   (default `ConfigurationInterface::ANY_ORIGIN` which means that any domain can make requests to the API)
-- `allowed_headers`: an array of custom headers allowed
-- `allowed_max_age`: the maximum age, the preflight response may be cached by a client
-- `credentials_allowed`: if a request is allowed to pass cookies
+- `allowed_headers`: an array of allowed custom headers
+- `allowed_max_age`: the maximum duration, since the preflight response may be cached by a client
+- `credentials_allowed`: allows a request to pass cookies
 - `exposed_headers`: an array of headers which are being exposed by the endpoint
 
 Save and close the file.

mkdocs.yml

@@ -30,6 +30,11 @@ nav:
           - "Content Validation": v4/core-features/content-validation.md
           - "Exceptions": v4/core-features/exceptions.md
           - "CORS": v4/core-features/cors.md
+      - Commands:
+          - "Create admin account": v4/commands/create-admin-account.md
+          - "Generate database migrations": v4/commands/generate-database-migrations.md
+          - "Display available endpoints": v4/commands/display-available-endpoints.md
+          - "Generate tokens": v4/commands/generate-tokens.md
       - Tutorials:
           - "Creating a book module": v4/tutorials/create-book-module.md
       - Transition from API Tools: