[KEYCLOAK-4992] - Allow clients to limit the number of permission in a RPT when using entitlements

authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc

@@ -36,7 +36,30 @@ curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
 Clients can use ```include_resource_name``` to decide whether or not resource`s name should be included on each permission granted by the server. This option
 can be used to reduce the size of RPTs and optimize client-server communication.
 
-By default, permissions in a RPT contain both the id and name of the resource that was granted for every single permission. This option is specially useful
+By default, permissions in a RPT contain both the id and name of the resource that was granted by every single permission. This option is specially useful
 when the resource server is capable of map their resources only based on the resource`s id.
 
+==== Limiting the number of permissions within a RPT
+
+.limit
+```bash
+curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
+    "metadata" : {
+        "limit" : 10
+    },
+    "permissions" : [
+        ...
+    ]
+}' "http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement/{client_id}"
+```
+Clients can use ```limit``` to specify how many permissions they expected within a RPT returned by the server. The limit option works as follows:
+
+* If a request is sent *without* a previously issued RPT, only ```limit``` permissions will be returned based on the resources/scopes from the ```permissions``` claim.
+* If a request is sent *with* a previously issued RPT, the permissions associated with the resources/scopes from the ```permissions``` claim take precedence where the permissions
+from the previously issued RPT are only included if ```limit``` is not reached. In case there is enough room for permissions from a previously issued RPT, the server
+will include the first permissions defined there.
+
+This option allows clients to control the size of RPTs and keep only last permissions granted by the server. It usually makes sense only in cases your client
+is capable of sending previously issued RPTs while asking for new permissions (a.k.a.: incremental authorization).
+