updated references to authentication

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

@@ -24,11 +24,46 @@ This allows users to exchange their credentials (username/password) for access t
 These tokens are then used for later requests instead of repeatedly sending credentials.
 
 Authentication in Dotkernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already configured out of the box.
-To customize authentication behavior (token lifetimes, algorithms, etc.), edit `config/autoload/local.php` under the `authentication` key.
+To customize authentication behavior (token lifetimes, algorithms, etc.), edit `config/autoload/authentication.global.php` under the `authentication` key.
 See the [Mezzio OAuth2 documentation](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration) for all available options.
 
+> The `authentication.global.php` file applies from Dotkernel API versions after 7.2.
+> In Dotkernel API 7.2 and earlier, the `authentication` key is in `config/autoload/local.php`.
+
 > You can check the [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration) configuration part for more info.
 
+### Token lifetime format
+
+The token lifetimes are set as [DateInterval](https://www.php.net/manual/en/dateinterval.construct.php) strings, under the `authentication` key in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier):
+
+| Key                    | Default | Controls                                  |
+|------------------------|---------|-------------------------------------------|
+| `access_token_expire`  | `P1D`   | How long an access token is valid         |
+| `refresh_token_expire` | `P1M`   | How long a refresh token is valid         |
+| `auth_code_expire`     | `PT10M` | How long an authorization code is valid   |
+
+A value is made of:
+
+- `P`, followed by date units: `D` days, `W` weeks, `M` months, `Y` years
+- `PT`, followed by time units: `H` hours, `M` minutes, `S` seconds
+- a number before each unit, e.g. `P2D` or `PT10M`
+
+Date and time units can be combined in one value, with the `T` separating them.
+
+Examples:
+
+| Value     | Meaning                    |
+|-----------|----------------------------|
+| `P1D`     | 1 day                      |
+| `P1M`     | 1 calendar month           |
+| `P30D`    | exactly 30 days            |
+| `P2DT3H`  | 2 days and 3 hours         |
+| `PT10M`   | 10 minutes                 |
+| `PT3600S` | 3600 seconds (1 hour)      |
+
+> `P1M` is a calendar month, so its length in days depends on the month it starts in.
+> Use `P30D` if the lifetime must be exactly 30 days.
+
 ## How it works
 
 Dotkernel API authentication system can be used for SPAs (single-page applications), mobile applications, and simple, token-based APIs.
@@ -226,7 +261,7 @@ The client values come from `oauth_clients` and the scope from `oauth_scopes`.
 
 **Q: How long do the tokens last?**
 
-A: Access tokens expire after one day and refresh tokens after one month, both configurable under the `authentication` key in `config/autoload/local.php`.
+A: Access tokens expire after one day and refresh tokens after one month, both configurable under the `authentication` key in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier), see [Token lifetime format](#token-lifetime-format).
 
 **Q: How do I renew an expired access token?**
 

docs/book/v7/introduction/file-structure.md

@@ -50,14 +50,15 @@ This folder contains all application-related config files:
 
 This folder contains all service-related local and global config files:
 
+* `authentication.global.php` - Configures OAuth2 authentication: key paths, token lifetimes and the invalid credentials message (added after 7.2; in 7.2 and earlier this lives in `local.php`)
 * `authorization.global.php` - Configures access per route for user roles
 * `cli.global.php` - Configures cli
 * `content-negotiation.global.php` - Configures request and response formats
 * `cors.local.php.dist` - Configures Cross-Origin Resource Sharing, like call origin, headers, cookies
 * `dependencies.global.php` - Sets global dependencies that should be accessible by all modules
 * `development.local.php.dist` - Gets symlinked into place when enabling development mode; activates error handlers
 * `error-handling.global.php` - Configures and activates error logs
-* `local.php.dist` - Local configuration file: database credentials, application name and URL, OAuth2 key paths
+* `local.php.dist` - Local configuration file: database credentials, application name and URL (in 7.2 and earlier, also the OAuth2 key paths)
 * `local.test.php.dist` - Local configuration for functional tests
 * `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging. Not committed: the post-install script copies it out of `dotkernel/dot-mail` during installation (in 7.0 this file is `mail.global.php`)
 * `mezzio.global.php` - Mezzio core config file

docs/book/v7/introduction/introduction.md

@@ -29,7 +29,7 @@ Below is a quick overview of features in Dotkernel API and how they interconnect
 
 | Feature             | Purpose                            | Configuration                                  |
 |---------------------|------------------------------------|------------------------------------------------|
-| OAuth2              | Authentication                     | config/autoload/local.php                      |
+| OAuth2              | Authentication                     | config/autoload/authentication.global.php      |
 | RBAC                | Authorization                      | config/autoload/authorization.global.php       |
 | Content Negotiation | Request/response format validation | config/autoload/content-negotiation.global.php |
 | OpenAPI/Swagger     | API documentation                  | Auto-generated                                 |
@@ -148,7 +148,7 @@ A: REST APIs in a microservices setup, headless CMS backends, e-commerce and Saa
 
 **Q: Where do I configure each feature?**
 
-A: OAuth2 in `config/autoload/local.php`, RBAC in `config/autoload/authorization.global.php`, content negotiation in `config/autoload/content-negotiation.global.php`; the OpenAPI documentation is generated by `composer openapi` and configured in `config/autoload/openapi.global.php`.
+A: OAuth2 in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier), RBAC in `config/autoload/authorization.global.php`, content negotiation in `config/autoload/content-negotiation.global.php`; the OpenAPI documentation is generated by `composer openapi` and configured in `config/autoload/openapi.global.php`.
 
 **Q: How do I register a new module?**
 

docs/book/v7/security/oauth2-security.md

@@ -17,7 +17,8 @@ These clients **must not** remain unchanged in your production environment, as t
 
 ## OAuth Token Lifetime and Refresh Hygiene
 
-The configuration for OAuth2 tokens can be edited in `config/autoload/local.php` under the `authentication` key.
+The configuration for OAuth2 tokens can be edited in `config/autoload/authentication.global.php` under the `authentication` key (`config/autoload/local.php` in 7.2 and earlier).
+The values use the `DateInterval` format, explained in [Token lifetime format](../core-features/authentication.md#token-lifetime-format).
 
 By default, the lifetimes of the `access` and `refresh` tokens are set to one day and one month respectively.
 Make sure to adjust their values in accordance with your application's needs, with lower values being generally safer.
@@ -67,7 +68,7 @@ They ship with passwords equal to their names, so leaving them in place hands an
 
 **Q: Where do I change token lifetimes?**
 
-A: Under the `authentication` key in `config/autoload/local.php`.
+A: Under the `authentication` key in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier), using the [DateInterval format](../core-features/authentication.md#token-lifetime-format).
 Defaults are one day for access tokens and one month for refresh tokens; shorter values are generally safer.
 
 **Q: Can I invalidate a user's tokens before they expire?**

docs/book/v7/tutorials/token-authentication.md

@@ -152,7 +152,7 @@ You should see a `200 OK` response with the following JSON body:
 Field description:
 
 - `token_type`: token type to be set when sending the `Authorization` header (example: `Authorization: Bearer eyJ0e...`)
-- `expires_in`: access token lifetime (modify in: `config/autoload/local.php` > `authentication`.`access_token_expire`)
+- `expires_in`: access token lifetime (modify in: `config/autoload/authentication.global.php` > `authentication`.`access_token_expire`; `config/autoload/local.php` in 7.2 and earlier)
 - `access_token`: generated access token (store it for later use)
 - `refresh_token`: generated refresh token (store it for regenerating expired access token)
 
@@ -256,7 +256,7 @@ You should see a `200 OK` response with the following JSON body:
 Field description:
 
 - `token_type`: token type to be set when sending the `Authorization` header (example: `Authorization: Bearer eyJ0e...`)
-- `expires_in`: access token lifetime (change here: `config/autoload/local.php` `authentication`->`access_token_expire`)
+- `expires_in`: access token lifetime (change here: `config/autoload/authentication.global.php` `authentication`->`access_token_expire`; `config/autoload/local.php` in 7.2 and earlier)
 - `access_token`: generated access token (store it for later use)
 - `refresh_token`: generated refresh token (store it for regenerating expired access token)
 
@@ -392,7 +392,7 @@ A: Generating uses `grant_type: password` with a username and password; refreshi
 
 **Q: How long is an access token valid?**
 
-A: 86400 seconds — one day — configurable via `authentication`, `access_token_expire` in `config/autoload/local.php`.
+A: 86400 seconds — one day — configurable via `authentication`, `access_token_expire` in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier).
 
 **Q: I get `400 Bad Request` with "Invalid credentials". What should I check?**