The ability to share content with others is fundamental to the way people use Dropbox. Using the Dropbox API, You can safely control your sharing with highly-configurable options, controls, and permission structures.
There are a few ways to share content with the Dropbox API:
- Create a shared link with /sharing/create_shared_link_with_settings. Shared links are a great way to share content with non-Dropbox users
- Add users to a shared folder with /sharing/add_folder_member. Shared folders are a powerful tool to collaborate or manage distributed work.
- Add users to an individual file /sharing/add_file_member to create a shared file. Shared files are useful for securely granting access to specific content.
Files and folders in Dropbox may be shared via a shared link. These shared links are publicly accessible by default, but may be set to expire and/or have their visibility limited to logged-in team members or to those with the password. When you share a link with someone, they can view and download that content with the same quality as the original file.
Creating Shared Links
Using the Dropbox API, you create shared links by calling /sharing/create_shared_link_with_settings. The endpoint takes two parameters: path and settings.
The path parameter is a file reference and can be a file path, file id, revision, or namespace relative path. The settings parameter controls the behavior and visibility of the shared link. An existing shared link’s settings can be modified by calling /sharing/modify_shared_link_settings.
Some examples:
- An accountant wants to securely provide a completed tax packet to their client by using a shared link with a password. Their settings include requested_visibility set to password and the link_password set to a private password they share with their client.
- A teacher running an all day science lab wants to provide students with access to research materials for a limited amount of time. They create a shared link to a folder that will expire after a set period of time by using the expires parameter.
Shared Link Visibility
If no settings are provided, then the shared links will default to pubic visibility, but are subject to the folder’s sharing policy which may be set to team only. Folder sharing policies are covered in the “Shared folders” section of this guide.
Editable Shared Links
For most content in Dropbox, shared links are view-only and download-only. However, for files that can be edited in the cloud (like Microsoft, Google, or Paper), it is possible to create shared links that grant the recipient permission to edit. This can be done by setting access to editor in a the shared link settings for a cloud-editable file.
For cloud-editable files, if the audience is set to no_one, then the link serves as a pointer to the content but access is limited to the pre-existing access rights.
How Shared Links Relate to Files
For cloud-editable files like the ones mentioned above, the shared link generated is unique to that content. That means if multiple users create a shared link to the same cloud-editable file it will be the same link. However, that behavior only applies to cloud-editable files.
For most files in Dropbox, any shared links that are generated are unique to a specific user. In other words, the shared link I create to cat_in_a_box.jpg is different than the shared link you create to the same file. This distinction is relevant for team apps.
Reading Shared Links
The /sharing/list_shared_links endpoint will return all shared links that allow access to a given path for the given user. If no path is provided, the endpoint will return all shared links for the user making the API call.
The default behavior of the endpoint is to provide shared link visibility flowing upwards in the folder structure. When given a specific path to a file or folder, the return will include direct links to the given path and links to its parent folder. However, the inverse is not true and shared link visibility does not flow downwards.
An example:
- Calling /sharing/list_shared_links with path="/Homework" does not return links to “/Homework/Cat_Research.docx”.
- Calling /sharing/list_shared_links with path="/Homework/Cat_Research.docx" returns shared links to that file and links to “/Homework”.
Example /sharing/list_shared_links output with path="/cat pictures/bed_cat.jpg":
{
"links": [
{
".tag": "file",
"url": "https://www.dropbox.com/s/n0jo32rbghvdpll/bed_cat.jpg?dl=0",
"id": "id:odTlUvbEAAAAAAAAAF3Q",
"name": "bed_cat.jpg",
"path_lower": "/cat pictures/bed_cat.jpg",
"link_permissions": {
// link permissions
},
"team_member_info": {
// team member info
},
{
".tag": "folder",
"url": "https://www.dropbox.com/sh/ohne9yvmzrfkmso/AADYv8Gh2P9oJSKln-RW2ZVca?dl=0",
"id": "id:odTlUvbpIEXAAAAAAAAGBA",
"name": "Cat Pictures",
"path_lower": "/cat pictures",
"link_permissions": {
// link permissions
},
"team_member_info": {
// team member info
}
],
"has_more": false
}Interacting with Shared Links
It’s possible to use a shared link to interact directly with the Dropbox API. You can read data, download files, or make changes to existing shared links.
You’re able to adjust the settings on your shared link with /sharing/modify_shared_link_settings.
You can use a shared link to retrieve metadata by calling /sharing/get_shared_link_metadata. Optionally, if you have a shared link to a folder and need metadata for something inside it, you can pass the shared link and use the path parameter to retrieve metadata for a nested file or subfolder.
A shared link can be used to download a file by calling /sharing/get_shared_link_file. Similar to /get_shared_link_metadata, this endpoint’s path parameter can be used to reference (and download) a file inside a shared link to a folder.
Shared folders are an intuitive and powerful way to share Dropbox content with others. Using shared folder Shared folders may have an owner, and any number of viewers and editors. These may be individual users or groups. The actions that folder members may take are defined by the shared folder’s policy, which is covered in a section below.
Adding Shared Folder Members
New members can be added to the shared folder with the /sharing/add_folder_member endpoint.
New shared folder members are notified over email by default. However, this behavior can be silenced using the quiet parameter or modified to include a message using custom_message.
Shared folder members that are new to Dropbox will be invited to create an account in the initial email. All members must be logged into Dropbox in order to access the folder.
New members can be added by shared folder owners or editors, but that behavior can be modified in the shared folder policy.
Reading Shared Folder Membership
You can list the members of a shared folder by calling /sharing/list_folder_members. It is possible to specify the number of members returned using the limit parameter, but the maximum (and default) is 1,000. To paginate over any remaining members you need to pass the returned cursor to /sharing/list_folder_members/continue.
Listing Received Folder Shares
You can view a list of folders shared with a user by calling /sharing/list_folders (and /sharing/list_folders/continue for paginated results).
It is possible that some of the users shares are not mounted due to either not acting on an invitation to a shared folder or by explicitly unmounting that shared folder. The shared folder won’t appear in the user’s Dropbox until it is mounted. See the end user documentation here.
Mounted and Unmounted Shared Folders
When new members are added to shared folders, they’re invited to add the shared folder to their Dropbox account. Once the folder has been added, it is considered mounted, which means the folder is synced to a user’s Dropbox and returned in /files/list_folder calls to the folder’s mount point. When a member has been invited to the shared folder but hasn’t added it to their Dropbox yet (or has explicitly unmounted it), it is considered unmounted, which means the folder is not synced to a user’s Dropbox, not included in view or list calls, but can be mounted at a later time.
You can view a list of a user’s available shares by calling /sharing/list_folder or /sharing/list_mountable_folders (and /sharing/list_mountable_folders/continue for any paginated results). The path_lower property indicates a mount point, and the absence of the property indicates the share is unmounted. Unmounted shares will be available until the user is explicitly removed or the folder is unshared.
You can mount a user’s available shares by calling /sharing/mount_folder and unmount existing shares by calling /sharing/unmount_folder.
Shared Folder Policy
Shared folders have policies around folder membership, ACL modifications, and shared links. Information about a shared folder’s policy is returned with shared folder metadata. A shared folder’s policy can be updated with /sharing/update_folder_policy. The shared folder policy is returned with calls that list shared folder metadata. Updating the shared folder policy can be particularly valuable for teams.
Example /sharing/list_folders output:
{
"entries": [
{
"access_type": { ".tag": "owner" },
"is_inside_team_folder": false,
"is_team_folder": false,
"name": "dir",
"policy": {
"acl_update_policy": { ".tag": "owner" },
"shared_link_policy": { ".tag": "anyone" },
"member_policy": { ".tag": "anyone"},
"resolved_member_policy": { ".tag": "team" }
},
"preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
"shared_folder_id": "84528192421",
"time_invited": "2020-05-22T00:07:40Z",
"path_lower": "/dir",
"permissions": [],
"access_inheritance": {
".tag": "inherit"
}
}
],
"cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}Files in Dropbox may be explicitly shared with other users without the use of a shared link or shared folder.
Adding file members
The endpoint to share a file is /sharing/add_file_member. A file can be shared with an individual account, multiple accounts, or a group (covered in the “Team considerations” section of the guide). Sharing a file can be completed in a single step (compared to sharing a folder which may require multiple steps).
The user must be logged into Dropbox in order to access the file. New users will be invited to create an account when the file is shared with them. Similar to a shared folder, the notification behavior can be modified using quiet or custom_message.
Reading file membership
To determine which files have been shared, you can include the include_has_explicit_shared_members parameter in a /files/list_folder call. The list of files in the response will include a boolean indicating if a file has explicit shares.
If a file has been shared, then you can list the members that file has been shared with by calling the /sharing/list_file_members endpoint (and /sharing/list_file_members/continue if your results have been paginated).
Example /sharing/list_file_members output:
{
"users": [
{
"access_type": {
".tag": "viewer"
},
"permissions": [],
"is_inherited": false,
"invitee": {
".tag": "email",
"email": "hello@dropbox.com"
}
}
],
"groups": [],
"invitees": [
{
"access_type": {
".tag": "editor"
},
"permissions": [],
"is_inherited": false,
"user": {
"account_id": "dbid:AAbuEftqA88UpoeExe7rcSo68ADcrWnBMk",
"email": "example@email.com",
"display_name": "John Doe",
"same_team": false
}
}
]
}By default, the results include members that were explicitly shared and members that were inherited. An inherited member is granted access from a parent folder. This behavior can be turned off with the include_inherited parameter.
Listing File Shares
You can retrieve a list of files that have been explicitly shared with a user with the /sharing/list_received_files endpoint (and /sharing/list_received_files/continue if the results have been paginated). The list does not include file invitations to files that are unclaimed.
Team Considerations
Dropbox Business teams have access to some additional sharing mechanisms. Additionally, there are some scenarios to sharing that require special consideration on a team.
Namespaces
Understanding namespaces can help you traverse and manage team content more effectively. Read about namespaces in the Namespace Guide.
Using Groups to Manage Shares
Folders and files can be shared with groups. When team members join that group, they’ll automatically have access to those shares. Similarly, they’ll lose access when removed from that group. You can manage group membership by adding (/team/groups/members/add) and removing (/team/groups/members/remove) team members.
Detecting shared links
Shared links created between a user and content are associated with the user that created them. In other words, the shared link I create to cat_in_a_box.jpg is different than the shared link you create to the same file.
In order to detect all shared links to a specific file, you need to check each user’s shared links. Here is the pattern you would follow:
- Call /team/members/list and /team/members/list/continue to list all members of a team.
- Call /sharing/list_shared_links on behalf of each team member with the Dropbox-API-Select-User header.
- Parse the output to look for shared links to a specific file.
Team Folders
Dropbox Business teams have access to team shared spaces, which are managed by the team administrator and supported nested shares. Depending on team features (/team/features/get_values), this is in the form of:
- Team folders, which behave similar to shared folders but are owned by a team and support nested shares.
- Team Space, which is a shared structure shared by the team which serves as the root for each individual member folder.
Additional Resources
We have some recommended reading to help comprehend some of the information covered in this guide.
- [Developer blog post] 3 ways to add sharing to your Dropbox App.
- [Developer blog post] Manage team sharing in your Dropbox app.
