# Shares
Files in Onedata can be shared i.e. made available for unauthenticated users in read-only mode. It's achieved using Shares — semi-public links that can be passed to desired recipients. Anyone on the Internet with a Share link can read the data, but the link is impossible to guess (hence the semi-public nature of Shares). Shares may have an optional description in Markdown format to improve their comprehension and usability for the target audience.
Both directories and files can be shared, and multiple Shares may be created for the same file/directory. It is possible to share a whole Space.
# Sharing a file or directory
To create a Share, navigate to the file browser, open the context menu for a file or directory, and choose Share / Publish.
You will see a modal in which you can enter a Share name that will be visible to other users. Click on the Create button to proceed with the Share creation.
NOTE
The Share root directory serves as the starting point for shared items and contains all the files and folders that are nested in the directory. However, it's worth mentioning that nested items within the Share root directory do not have individual Shares associated with them, even though they are effectively shared.
After the successful Share creation, a right-side details panel with the Shares tab will appear containing a list of Shares created for a selected file or directory.
NOTE
A single file or directory can be shared multiple times, each with a different name and unique URL, which helps to manage access to files across many users, for example, if you want to withdraw a link shared with a specific group, create a specific description, etc. Creating multiple Shares can be performed using the Create another share button in the Shares tab of the file information panel.
An authenticated user can access a Share management view by clicking on the Show details link beside a Share name, whereas the Share URL can be copied and shared with others to grant anonymous, read-only access to the files.
# Anonymous Share access
Accessing the Share URL opens an anonymous Share view which by default contains a Files tab with a file browser listing a single shared item (a file or a directory).
By default, anonymous users can simply browse these files in a read-only manner, and also:
- download files,
- see files information like File ID, modification time and size,
- read files metadata extended attributes that can be set by authenticated users.
Access to specific files can be restricted inside the Share by modifying the following permissions of files in the file browser:
- changing POSIX Other (anonymous) Read and Execute flag,
- or setting ACL permissions for a special ANONYMOUS user class.
You can do it by navigating to the Data > Space name > Files view and choosing Permissions from the context menu for the file or directory to which you want to restrict access. For more information about the web file browser permissions view, refer to this page.
NOTE
Although there is a POSIX Other — Write flag and modification permissions available for the ANONYMOUS special ACL user, these don't affect the ability to write files by anonymous users — shared files are always read-only for anonymous users.
The file details panel also provides an API tab that provides curl commands for retrieving information about files by unauthenticated users.
# Managing Shares
You can list your Shares per file, per space, or show Shares across all spaces accessible by you.
# Listing per file
A single file or directory can be shared multiple times — each with a different URL. If there are some Shares available for the file, you can simply access the Shares tab by clicking on the Shared badge in the file browser.
MOBILE DEVICES NOTE
As the file badges are not clickable on mobile devices, you can access the Shares list by choosing Information from the file actions menu and opening the Shares tab in the right-side panel.
The Share tab name includes a number with the shares count per file. Clicking on the Show details link beside a Share name opens a Share management view, while clicking on the "Create another share" button will bring a Share creation modal.
# Listing per space
To list all shares created in the space, navigate to the Data > Space name > Shares, Public Data view. Clicking on a Share row in the main view will open a Share management view, while the actions menu for the Share provides the following operations: Rename, Remove share, and Copy Share URL.
# Listing all shares in all your spaces
To list all shares from all your spaces, open a Shares tab from the navigation bar, which will show the list in the Shares sidebar. Click on a Share item to open a Share management view.
# Share management view
The single Share management view enables you to view shared data and the Share information as well as configure it. The view consists of:
- a Path to the shared file or directory in the space,
- a Share link to access the Share by anonymous users,
- a Description tab that allows creating an information page describing the Share,
- a Files tab that allows you to browse files as seen as an anonymous user,
- an Expose as Public Data tab, which allows exposing the data collection as Public Data.
The Share can be also renamed or removed using the actions menu in the upper-right corner of the view.
# Share Description
You can add an optional description of the Share using Markdown format. After opening the Description tab, click on the Create description button and write the description using Markdown markup. You can use the "Open preview" and "Edit markdown" buttons to switch between Markdown markup and rendered description and use Save or Discard buttons to persist or cancel changes. The description can be edited at any time after it is saved and published — applied changes will be immediately visible to the Share users.
The description will be visible to unauthenticated users that know the Share URL.
NOTE
Writing a Share description is recommended as it helps users understand what the data collection is about, what information it contains, and how it can be used. With a description, other users can quickly assess whether the collection is suitable for their needs.
# Files view
The Files tab provides a preview of the anonymous Share view, showcasing what an anonymous user will see when accessing it. This browser has limited functionality, allowing read-only operations that anonymous users can perform. To access the browser with all features available for authenticated users, open the parent directory link found in the Path section of the Share management view.
# REST Share information
Besides a Share link accessible in the web browser, you can show and copy a curl command giving information about sharing for the CLI, selecting the Share REST endpoint option from the URL dropdown.
For example, the following command:
curl https://dev-onezone.default.svc.cluster.local/api/v3/onezone/shares/b2c3bcd7ff9dc063e4226581175f21fbchc6a8/public
would result in the following JSON response:
{
"shareId": "b2c3bcd7ff9dc063e4226581175f21fbchc6a8",
"name": "My shared files",
"description": "# Description\nIn markdown format",
"rootFileId": "00000000007ED1B4736861726547756964233731666232643538646166323835616664623339303265663331653131646538636864626137236133613138616463346137376464316236313039363862326138353735633431636830643762236232633362636437666639646330363365343232363538313137356632316662636863366138",
"publicUrl": "https://dev-onezone.default.svc.cluster.local/share/b2c3bcd7ff9dc063e4226581175f21fbchc6a8",
"publicRestUrl": "https://dev-onezone.default.svc.cluster.local/api/v3/onezone/shares/b2c3bcd7ff9dc063e4226581175f21fbchc6a8/public",
"handleId": null,
"fileType": "dir",
"creationTime": 1685193979
}
TIP
For full Share API reference, see the Share (opens new window) chapter of the Onedata REST API documentation.