Skip to main content

Sharing API

Grant other users or deployments access to a resource without exposing it to the Public space, using the DIAL Core Sharing API. This guide is for developers building sharing workflows on top of the Unified API. You should understand DIAL access control and how resources are stored in private spaces.

In DIAL, a resource is a conversation, prompt, file, or application, owned by a user or a deployment (an application or Toolset). When created, a resource lives in its owner's private folder. Sharing grants specific recipients access to it while keeping it out of the public file space. When a user shares a resource, it becomes available in DIAL Chat and the Catalog, where recipients can discover and use it.

The Sharing API has two perspectives: the resource owner and the resource recipient. It also includes a separate set of endpoints for deployments that need to share resources with each other during a request.

note

Users can authenticate to the Sharing API with either a JWT or an API key. Deployments must use per-request keys.

Endpoints for resource owners​

EndpointDescription
createShare a resource by creating an invitationLink that contains an invitationId. Grant READ or WRITE access. Add the SHARE permission to let recipients re-share the resource with READ access; use maxAcceptedUsers to cap how many users can accept the link (unlimited by default). SHARE can only be combined with another permission, and re-sharing is limited to READ. The system does not support listing all recipients of a shared resource.
copyAdd permissions for a new resource. For example, when a new attachment is added to an already-shared conversation, this ensures recipients can access the updated resource, including the new attachment.
listQuery all resources you have shared. Send "with": "others" in the request body. When a conversation with attachments is shared, the attachments appear as separate shared resources.
revokeStop sharing a resource. The content becomes inaccessible to all recipients, and any associated invitation link stops working.
invitationsList all active invitations you have created. Invitations are created by the create endpoint.
invitations/{invitationId}Use the DELETE method to revoke a specific invitation.
note

When an owner or recipient changes a shared resource, DIAL Core uses the HTTP ETag to version the resource and resolve conflicts. Use the Subscribe API to be notified of changes made by other users or deployments.

Endpoints for resource recipients​

EndpointDescription
discardStop using a shared resource. The resource is no longer marked as shared for the owner.
listQuery all resources shared with you. Send "with": "me" in the request body.
invitations/{invitationId}Use the GET method to view invitation details and to accept the invitation.
createRe-share a resource you received with the SHARE permission, creating a new invitationLink. You can grant only READ access when re-sharing.

Workflow examples​

Basic workflow​

  1. The owner shares a resource with create and gives the invitation link to the recipient.
  2. The recipient extracts the invitationId from the link and calls invitations/{invitationId} to accept the resource.
  3. The recipient lists shared resources and their details with list.

Revoke workflow​

  1. The owner shares a resource with create and gives the invitation link to the recipient.
  2. The recipient accepts the resource with invitations/{invitationId}.
  3. The owner revokes access with revoke.
  4. The recipient can no longer access the resource.

Re-share workflow​

  1. The owner shares a resource with create, including the SHARE permission, and gives the invitation link to the recipient.
  2. The recipient accepts the resource with invitations/{invitationId}.
  3. The recipient re-shares the resource with create and gives a new invitation link to a second recipient.
  4. The second recipient accepts the resource with invitations/{invitationId}.
  5. The second recipient lists shared resources with list.

Re-sharing rules​

The SHARE permission lets a recipient re-share a resource. A re-shared resource is always granted with READ access only. DIAL Core validates each re-share request and returns 400 when a rule is violated:

  • The original owner must have shared the resource with the SHARE permission.
  • The invitation must be within its time-to-live, governed by the invitation_ttl DIAL Core dynamic setting.
  • The re-share permission set must not include WRITE — only READ is allowed for re-sharing.
  • The number of accepted invitations must not exceed the limit set by the max_accepted_users dynamic setting or by maxAcceptedUsers in the original share request.

For these limits, see the configuration reference.

Sharing in DIAL Chat​

Chat users can share resources, accept invitations, and view resources shared by or with them, all from the UI. When a conversation that includes attachments is shared, the attachments are shared as well and can be opened through the chat file manager. For the end-user workflow, see the DIAL Chat user guide.

Sharing between deployments​

DIAL includes a separate API for cases where deployments — applications and Toolsets — need to share their private resources with each other to complete a task. For example, an application may need to give another application access to its files.

Authorization​

Deployments must authenticate to this API with per-request keys only. A request authorized with an API key or JWT is rejected: 403 Unauthorized - Operation is only permitted by per request API key.

Time-to-live​

The owner controls the time-to-live of granted permissions within the scope of the current request. The recipient can access the shared resource only during the request timeline.

Re-sharing between deployments​

Granted permissions are not transitive — a recipient deployment cannot re-share them. For example, if an application grants another application read access to a file, the recipient cannot pass that access to a third deployment; it must be granted explicitly through the permissions API. Permissions granted by the owner are revoked automatically once the recipient completes the current request.

The exception is interceptors: when a resource is shared with a deployment that has interceptors, those interceptors gain access to the resource as well.

Endpoints​

EndpointDescription
per-request-permissions/grantShare a resource by path with another deployment, identified by its ID. Grant READ and WRITE access. The recipient implicitly accepts the invitation.
per-request-permissions/revokeExplicitly revoke access. Until access is revoked, the recipient can reuse the permission on identical subsequent calls.
per-request-permissions/listList permissions granted by or to a specific deployment.

Example​

In this scenario, an application shares READ and WRITE access to a folder with another application, the recipient:

  1. The application calls per-request-permissions/grant to share its folder files/<app_bucket>/appdata/<folder> with the recipient deployment applications/<user_bucket>/<recipient_app>, granting READ and WRITE:

    {
      "resources": [
        {
          "url": "files/<app_bucket>/appdata/<folder>",
          "permissions": ["READ", "WRITE"]
        }
      ],
      "receiver": "applications/<user_bucket>/<recipient_app>"
    }

  2. DIAL Core records the grant against the application's per-request key.

  3. The application calls the recipient to perform an action that needs the shared folder.

  4. DIAL Core issues a new per-request key to the recipient and, finding that the application shared resources with it, records the grant against the recipient's key.

  5. The recipient writes to the shared folder through DIAL Core.

  6. When the recipient's call completes, DIAL Core invalidates its per-request key and the associated permissions.

Result​

You can share resources with users and deployments, manage invitations, revoke access, support controlled re-sharing, and grant transient access between deployments during a request.

Further reading​