Add new endpoint checkpermissions

documentation/src/main/resources/_data/sidebars/ditto_sidebar.yml

@@ -307,7 +307,7 @@ entries:
             output: web
             subfolders:
               - title: Checking Permissions for Resources
-                url: /check-permissions.html
+                url: /basic-auth-checkpermissions.html
                 output: web
           - title: Messages
             url: /basic-messages.html

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -10466,7 +10466,7 @@ components:
           entityId: "org.eclipse.ditto:some-thing-1"
           hasPermissions: [ "READ" ]
         lamp_toggler:
-          resource: "message:/features/lamp/inbox/toggle"
+          resource: "message:/features/lamp/inbox/message/toggle"
           entityId: "org.eclipse.ditto:some-thing-1"
           hasPermissions: [ "WRITE" ]
     PermissionEntityCheck:
@@ -10475,14 +10475,16 @@ components:
       properties:
         resource:
           type: string
-          description: "Resource path the permission check applies to."
+          pattern: "^(thing|message|policy):(/[a-zA-Z0-9._-]+)*$"
+          description: "Resource key to be checked, beginning with 'thing:', 'message:', or 'policy:', followed by the specific resource path. This defines the scope of the permission request."
         entityId:
           type: string
-          description: "ThingId of the entity performing the action."
+        description: "ID of the entity performing the action, which could be a ThingId or PolicyId, depending on the resource context."
         hasPermissions:
           type: array
           items:
             type: string
+            enum: [ "READ", "WRITE" ]
           description: "Required permissions on the resource."
     PermissionCheckResponse:
       type: object

documentation/src/main/resources/pages/ditto/baic-auth-checkpermissions.md

@@ -2,10 +2,10 @@
 title: Checking Permissions for Resources  
 keywords: permissions, authorization, resources, policy, checkPermissions  
 tags: [model]  
-permalink: check-permissions.html  
+permalink: basic-auth-checkpermissions.html  
 ---
 
-The `/checkPermissions` endpoint allows clients to validate permissions for various entities and resources.
+The `/checkPermissions` endpoint allows clients to validate permissions for specified entities on various resources, verifying access rights as defined in Ditto's policies.
 
 ## Overview
 
@@ -18,24 +18,31 @@ Submit a `POST` request with a JSON payload specifying entities, resources, and
 
 ```json
 {
-  "entity_name": {
-    "resource": "resource_path",
-    "entityId": "thingId",
-    "hasPermissions": ["READ", "WRITE"]
-  }
+    "entity_name": {
+        "resource": "thing:/features/lamp/properties/on",
+        "entityId": "org.eclipse.ditto:some-thing-1",
+        "hasPermissions": ["READ"]
+    },
+    "another_entity": {
+        "resource": "message:/features/lamp/inbox/message/toggle",
+        "entityId": "org.eclipse.ditto:some-thing-2",
+        "hasPermissions": ["WRITE"]
+    }
 }
 ```
-- entity_name: Name representing the entity.
-- resource: Path of the target resource (e.g., thing:/features/light/properties/on).
-- entityId: Unique identifier for the entity (thingId).
-- hasPermissions: List of permissions required (READ, WRITE).
-- 
+## Fields
+- entity_name: Identifier for the entity performing the action.
+- resource: Path of the target resource, starting with thing:, message:, or policy: followed by a valid resource path.
+- entityId: Unique identifier for the entity, such as a thingId or policyId, depending on the resource.
+- hasPermissions: Array of required permissions, such as READ or WRITE.
+
 ## Response Structure
 The response indicates permission status for each entity and resource, returning a JSON object mapping entities to true (authorized) or false (unauthorized) values.
 
 ```json
 {
-  "entity_name": true
+  "entity_name": true,
+  "another_entity": false
 }
 ```
 This endpoint is especially useful for applications requiring quick permission validation for multiple entities across various resources.

documentation/src/main/resources/pages/ditto/httpapi-concepts.md

@@ -139,29 +139,6 @@ This maps to the following HTTP API endpoints:
 * `/policies/{policyId}/entries/{entryLabel-1}/resources`: accessing the resources of a single `Policy` entry with the
   label `{entryLabel-1}`
 
-#### `/checkPermissions` in API 2
-The checkPermissions endpoint verifies permissions for specified entities on various resources, ensuring they have the necessary access rights as defined in the policies.
-
-```json
-{
-    "lamp_reader": {
-        "resource": "thing:/features/lamp/properties/on",
-        "entityId": "org.eclipse.ditto:some-thing-1",
-        "hasPermissions": [
-            "READ"
-        ]
-    },
-    "lamp_toggler": {
-        "resource": "message:/features/lamp/inbox/toggle",
-        "entityId": "org.eclipse.ditto:some-thing-1",
-        "hasPermissions": [
-            "WRITE"
-        ]
-    }
-}
-```
-The response will confirm if each entity has the requested permissions.
-
 #### `/connections` in API 2
 
 The base endpoint for accessing and working with `Connections`.