chore: add deployment sharing api description (#361)

Author: sr-remsha

docs/platform/7.collaboration-intro.md

@@ -38,7 +38,9 @@ Published conversations and prompts become available to all DIAL Chat users. Pub
 
 ## Sharing
 
-In cases, when resource owners want to enable access to specific resources without making them public, they can create a sharing link and give it to specific users. This way other users get access to the resource but the resource itself stays in the private space of the resource owner who can modify it or withdraw access at any time.
+### Users
+
+In cases, when resource owners want to enable access to specific resources without making them public, they can create a sharing link and give it to specific users. This way other users get access to the resource but the resource itself stays in the [private space](/docs/platform/0.architecture-and-concepts/6.access-control.md#private-and-public-spaces) of the resource owner who can modify it or withdraw access at any time.
 
 Sharing is a great way to expose your resources to other users while keeping control over it. For example, you can share a conversation with a colleague to get feedback on it or share an application you developed with a team member to test it.
 
@@ -48,6 +50,10 @@ DIAL users can create a sharing link via both [DIAL Chat UI](/docs/tutorials/0.u
 
 When a resource is shared, it becomes available for a recipient(s) in DIAL Chat, [DIAL Marketplace](/docs/platform/4.chat/1.marketplace.md) and via DIAL Core API.
 
+### Deployments
+
+DIAL provides API for deployments (toolsets and applications) to share resources with each other or to access resources of DIAL users to perform specific actions. 
+
 ##### Additional Information: 
 
 > * Refer to [Conversations](/docs/tutorials/0.user-guide.md#share), [Prompts](/docs/tutorials/0.user-guide.md#share-1), [Applications](/docs/tutorials/0.user-guide.md#share-2) to see how DIAL Chat users can share them.

docs/tutorials/0.user-guide.md

@@ -1407,11 +1407,11 @@ For applications that are available organization-wide, you can copy and share a
 
 ### Toolsets
 
-In DIAL Marketplace you can find all [applications](#applications) and [language models](#models) available on your DIAL environment. Each user can access only those applications and models that are available to their [user role](/docs/platform/3.core/2.access-control-intro.md#roles-as-subjects).
-
 Toolsets are MCP servers that you can use as tools in [Quick Apps 2.0](#add-quick-app-20).
 
-In your workspace, you can access toolsets added on the Marketplace screen and add new toolsets. 
+In DIAL Marketplace you can find all toolsets available on your DIAL environment. Each user can access only those applications and models that are available to their [user role](/docs/platform/3.core/2.access-control-intro.md#roles-as-subjects).
+
+In [your workspace](#my-workspace), you can access toolsets added on the Marketplace screen and add new toolsets. 
 
 #### Authentication 
 
@@ -1437,8 +1437,6 @@ A toolset that does not require authentication does not display any label on its
 
 ![](./img/no-auth-toolset.png)
 
-Click **DIAL Marketplace** to navigate to the *home page* of DIAL Marketplace. Here, you can find all [applications](#applications) and [language models](#models) available on your DIAL environment for your [user role](/docs/platform/3.core/2.access-control-intro.md#roles-as-subjects), including all applications [published](#publish-2) in your organization and [shared](#share-2) with you by other users.
-
 ##### To log into your own toolset
 
 1. Select one of your won toolsets that requires authentication and click **Log in** in the actions menu. You can also find the **Login** button if you click the toolset card to see the details.
@@ -1466,7 +1464,7 @@ There can be two cases: a public toolset can be logged in and not.
 
 #### Add
 
-In your workspace, you can add new toolsets. Added toolsets are stored in a private folder of the toolset author in the DIAL filesystem. You can [publish](#publish-3) toolsets to list them on Marketplace and enable other users to access them.
+In [your workspace](#my-workspace), you can add new toolsets. Added toolsets are stored in a private folder of the toolset author in the DIAL filesystem. You can [publish](#publish-3) toolsets to list them on Marketplace and enable other users to access them.
 
 > Refer to [Access Control](/docs/platform/0.architecture-and-concepts/6.access-control.md) to learn more about private and public spaces.
 
@@ -1478,7 +1476,7 @@ In your workspace, you can add new toolsets. Added toolsets are stored in a priv
 2. Fill in the required fields. 
 3. When ready, click **Save and exit** to register the toolset in DIAL.
 
-> **Access toolset**: Your toolset will appear only in [My workspace](#my-workspace). To enable others to use it, share or [publish](#publish-3) your toolset. 
+> **Access toolset**: Your toolset will appear only in [your workspace](#my-workspace). To enable others to use it, share or [publish](#publish-3) your toolset. 
 
 |Field|Required|Description|
 |---|:---:|-------------|

docs/tutorials/1.developers/1.work-with-resources/1.sharing.md

@@ -2,6 +2,16 @@
 
 ## Introduction
 
+In DIAL, resources refers to conversations, prompts, files, and applications.
+
+A resource can be owned by DIAL users and deployments (applications and toolsets). By default, when a resource is created, it is placed in a [private folder](/docs/platform/3.core/2.access-control-intro.md#authorization-mechanisms) in the file storage and accessible only to its owner. However, DIAL provides sharing capabilities that allow resource owners to enable access their resources without exposing them to the public file space.
+
+DIAL users can use both [DIAL Chat UI](/docs/tutorials/0.user-guide.md#share) and [API](https://dialx.ai/dial_api#tag/Sharing) to share resources with other users or applications. When a resource is shared with other users, it becomes available in DIAL Chat and [DIAL Marketplace](/docs/platform/4.chat/1.marketplace.md), where users (with whom the resource has been shared) can discover and utilize it.
+
+DIAL provides a dedicated API for deployments to share their resources with each other.
+
+## DIAL API Users
+
 When you create resources in DIAL such as conversations, prompts, toolsets or applications, they are stored in a private space of your user and accessible only to you. You can use both DIAL Chat UI and API to enable access to your private resources to other users via a sharing link.
 
 In DIAL, [resources](/docs/platform/0.architecture-and-concepts/1.concepts.md) refers to conversations, prompts, files, and applications. When a resource is created or uploaded to DIAL, it is stored in a dedicated [storage bucket](/docs/platform/0.architecture-and-concepts/3.components.md#persistent-layer). You can use both DIAL Chat UI and API to share resources with other users or applications.
@@ -15,6 +25,8 @@ When a resource is shared, it becomes available in DIAL Chat and [DIAL Marketpla
 
 DIAL provides a set of REST API endpoints to work with sharing programmatically. There are two sides in the sharing process: the resource owner and the resource recipient. DIAL [Sharing API](https://dialx.ai/dial_api#tag/Sharing) has endpoints to facilitate workflows for either of them.
 
+> **Important**: DIAL users can use both [JWT](/docs/tutorials/2.devops/2.auth-and-access-control/1.jwt.md) and [API keys](/docs/tutorials/2.devops/2.auth-and-access-control/0.api-keys.md) to authenticate and authorize requests to the Sharing API.
+
 ### Endpoints for resource owners
 
 This table lists endpoints that resource owners can use to share resources and manage shared resources:
@@ -73,7 +85,7 @@ In the re-sharing case, a specific validation takes place:
 * The DIAL Core API will validate the permission set for the re-shared resource. The permission WRITE is not allowed to re-share resources: DIAL Core returns 400(Invalid permissions set. The permission READ is allowed for re-sharing only).
 * The DIAL Core API will validate the number of accepted invites per shared resource (based on `max_accepted_users` in the [DIAL Core dynamic settings](https://github.com/epam/ai-dial-core?tab=readme-ov-file#dynamic-settings)) and per invitation request (based on `maxAcceptedUsers` in the original share request). If the number exceeds the author's share limit, DIAL Core returns the error 400(The limit of maximum accepted invites is reached).
 
-## DIAL Chat UI
+### DIAL Chat UI
 
 Chat users can share their resources with others, accept sharing invitations, and view resources that have been shared by or with them. When conversations that include attachments are shared, all attachments are also shared and can be accessed through the chat file manager.
 
@@ -85,3 +97,55 @@ Refer to DIAL Chat user guide for details:
 * [Share prompts](/docs/tutorials/0.user-guide.md#share-1)
 * [Unshare prompts](/docs/tutorials/0.user-guide.md#unshare-1)
 * [Attachments Manager](/docs/tutorials/0.user-guide.md#attachments-manager)
+
+
+## DIAL API Deployments
+
+DIAL includes API for scenarios, when DIAL deployments (applications and toolsets) need to share their private resources with each other to perform specific actions. For example, a Mind Map application may need to use DIAL RAG files. 
+
+##### Authorization
+
+DIAL deployments (toolsets and applications) can use **only** [per-request API keys](/docs/platform/3.core/3.per-request-keys.md) to authenticate and authorize requests to the Sharing API. If a request is authorized by API key or JWT DIAL Core returns the error: `403 Unauthorized - Operation is only permitted by per request API key`.
+
+##### TTL
+The TTL of granted permissions to a shared resource is controlled by the resource owner in scope of the current request. The receiver has access to shared resources only during the request timeline.
+
+##### Re-Sharing
+
+Granted permissions are not transitive  - they cannot be re-shared with other deployments. For example, Mind Map grants permissions to DIAL RAG to read a file. If DIAL RAG wants to share access to this file with another deployment it should do it explicitly via permissions API. Eventually, permissions granted by the resource owner will be automatically revoked once the recipient completes the current request.
+
+The exception is made for [interceptors](/docs/platform/3.core/6.interceptors.md). If a resource is shared with another deployment which has interceptors, then those gain access to the resource as well. 
+
+##### Endpoints
+
+|Endpoint|Description|
+|-------|------------|
+|[`/per-request-permissions/grant`](https://dialx.ai/dial_api#tag/Sharing/operation/grantPerRequestPermissions)|Use this endpoint to share a specific resource by providing its path with another deployment by providing its ID. You can grant **READ** and **WRITE** access to a shared resource. As a result, the receiver implicitly accepts the invitation to the shared resource.|
+|[`/per-request-permissions/revoke`](https://dialx.ai/dial_api#tag/Sharing/operation/revokePerRequestPermissions)|Use this endpoint to explicitly revoke access to the shared resource. **Important**: The permissions can be reused by the caller in later calls. Unless access is explicitly revoked, the receiver can access the shared resource when making identical subsequent calls. |
+|[`/per-request-permissions/list`](https://dialx.ai/dial_api#tag/Sharing/operation/getPerRequestPermissions)|Use this endpoint to get a list of permissions granted by a specific deployment or to a specific deployment.|
+
+##### Example
+
+In this example scenario, a Mind Map application shares READ and WRITE access to its folder with DIAL RAG.
+
+1. Mind Map application makes a request to DIAL Core using the `/per-request-permissions/grant` endpoint to share access to its folder `files/<mind_map_bucket>/appdata/dial-rag` with DIAL RAG deployment `applications/<user_bucket>/dial-rag`, granting READ and WRITE permissions.
+
+    Example of the request body:
+
+    ```json
+    {
+    "resources": [
+        {
+        "url": "files/<mind_map_bucket>/appdata/dial-rag",
+        "permissions": ["READ", "WRITE"]
+        }
+    ],
+    "receiver": "applications/<user_bucket>/dial-rag"
+    }
+    ```
+
+2. DIAL Core creates a new record in API key data to be associated with Mind Map's per-request API key.
+3. Mind Map application makes a call to DIAL RAG to perform specific actions that require access to the shared folder.
+4. DIAL Core assigns a new per-request API key to DIAL RAG and checks if a caller (Mind Map) has shared any resources with it. If it did, DIAL Core creates a new record in API key data of DIAL RAG.
+5. DIAL RAG makes a call to DIAL Core to write into the shared folder.
+6. When the DIAL RAG API call to DIAL Core is completed, DIAL Core invalidates its per-request API key and API key data including permissions.