Sharing

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 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 and API 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, 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 refers to conversations, prompts, files, and applications. When a resource is created or uploaded to DIAL, it is stored in a dedicated storage bucket. You can use both DIAL Chat UI and API to share resources with other users or applications.

When a resource is shared, it becomes available in DIAL Chat and DIAL Marketplace, where users (with whom the resource has been shared) can discover and use it.

Refer to Collaboration Intro to learn more about sharing.

Refer to Access Control to learn about public and private resources in DIAL.

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 has endpoints to facilitate workflows for either of them.

Important: DIAL users can use both JWT and API keys 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:

Endpoint	Description
`create`	Resource owners can use this endpoint to share a resource by creating an `invitationLink` which includes an `invitationId`. Permissions: - You can grant READ or WRITE access to your resource. Note: If an app/user changes the shared resource, HTTP etag is used by DIAL Core to determine versioning and resolve conflicts. You can use Subscription API to get notifications about changes made by other users or applications. - Include a SHARE permission to enable recipients of the shared resource to re-share it with READ permissions. Use `maxAcceptedUsers` to apply limits on the number of users who can accept the invitation link - the default value is unlimited. Refer to Re-Sharing to learn more. Limitations: - The system does not support getting all the recipients of a shared resource. - SHARE permission can be used only in combination with other permission types. - Re-sharing is possible only with READ permission.
`copy`	Use this endpoint to add permissions for users to access a new resource. If a conversation with attachments has already been shared and a new attachment is added, this endpoint ensures that other users can access the updated shared resource, including the newly added attachment. This ensures proper access control for all shared components of the resource.
`list`	Use this endpoint to query the details of all resources that were shared by you. In the request body, provide `"with": "others"` to do that. Note, that in case you share a conversation with attachments, attachments are shared as well, but they will appear in the response as a separate shared resources.
`revoke`	Use this endpoint if you want to stop sharing a resource. As a result, the shared content becomes inaccessible to all recipients who previously had access to it, and any invitation link associated with it will no longer be valid for future use.
`invitations`	Invitations are created together with sharing resources using `/create` endpoint. Use `/invitations` endpoint to query a list of all active invitations you have created.
`invitations/{Invitation ID}`	Use this endpoint with the DELETE method to revoke a specific invitation.

Endpoints for resource recipients

This table lists endpoints that resource recipients can use to accept invitations and manage shared resources:

Endpoint	Description
`discard`	Recipients of a shared resource can use this endpoint to stop using shared resources. In this case, related resources will stop being marked as shared for the resource owner.
`list`	Use this endpoint to query the details of all resources that were shared with you. In the request body, provide `"with": "me"` to do that.
`invitations/{Invitation ID}`	Use this endpoint with the GET method to view invitation details and to accept an invitation.
`create`	Resource recipients can use this endpoint to re-share a resource by creating an `invitationLink` which includes an `invitationId`. Permissions: - You can grant READ access to the resource you want to re-share.

Workflow Examples

Basic workflow

Resource owner shares a resource using the /create and provides the invitation link for the resource recipient.
Resource recipient extracts the invitation id from the invitation link calls the /invitations/{Invitation ID} endpoint to accept the resource.
Resource recipient can now get the list of shared resources with their details via /list.

Revoke workflow

Resource owner shares a resource via /create and provides the invitation link for the resource recipient.
Resource recipient extracts the invitation id from the invitation link and calls the /invitations/{Invitation ID} to accept the resource.
Resource owner revokes access to the shared resource via /revoke.
Resource recipient cannot access the shared resource any longer.

Resource owner shares a resource via /create (with the SHARE permission type) and provides the invitation link for the resource recipient.
Resource recipient extracts the invitation id from the invitation link and calls the /invitations/{Invitation ID} to accept the resource.
Resource recipient can re-share the resource using the /create endpoint and provide the new invitation link for the new resource recipient.
New resource recipient extracts the invitation id from the invitation link and calls the /invitations/{Invitation ID} to accept the resource.
New resource recipient can now get the list of shared resources with their details via /list.

Resource owners can share resources with the SHARE permission type, which allows resource recipients to re-share the resource with other users or applications. When a resource is re-shared, the new recipient can only access the resource with READ permissions.

In the re-sharing case, a specific validation takes place:

The DIAL Core API will validate if the resource can be re-shared by examining if the resource's owner shared the resource with the permission SHARE. Otherwise, DIAL Core returns 400.
The DIAL Core API will validate invitation TTL by taking the invitation_ttl value from the DIAL Core dynamic settings.
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) 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

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.

Refer to DIAL Chat user guide for details:

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 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.

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. 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`	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`	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`	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.

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:
```
{
"resources": [
    {
    "url": "files/<mind_map_bucket>/appdata/dial-rag",
    "permissions": ["READ", "WRITE"]
    }
],
"receiver": "applications/<user_bucket>/dial-rag"
}
```
DIAL Core creates a new record in API key data to be associated with Mind Map's per-request API key.
Mind Map application makes a call to DIAL RAG to perform specific actions that require access to the shared folder.
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.
DIAL RAG makes a call to DIAL Core to write into the shared folder.
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.

Introduction​

DIAL API Users​

Sharing API​

Endpoints for resource owners​

Endpoints for resource recipients​

Workflow Examples​

Basic workflow​

Revoke workflow​

Re-share workflow​

Re-Sharing​

DIAL Chat UI​

DIAL API Deployments​

Authorization​

TTL​