How do I create a shared link in Dropbox API?

To create a shared link in the Dropbox API, you call the /sharing/create_shared_link_with_settings endpoint. This powerful endpoint allows you to programmatically generate links for your files, controlling various aspects like visibility and security.

Understanding the `create_shared_link_with_settings` Endpoint

The primary method for generating a shared link is by invoking the /sharing/create_shared_link_with_settings endpoint. This endpoint is designed for flexibility, enabling developers to define specific behaviors for the shared links they create.

This endpoint requires two main parameters:

path: Identifies the file for which the shared link will be created.
settings: Specifies the desired properties and permissions for the shared link.

Key Parameters for Shared Link Creation

The success and utility of your shared link depend heavily on how you define these two parameters.

1. The `path` Parameter

The path parameter serves as the reference to the file you wish to share. It's versatile and can accept several forms of identification:

File Path: A string representing the absolute path to the file within the user's Dropbox, e.g., "/Homework/Math/Final.docx".
File ID: A unique identifier assigned by Dropbox to a specific file, often used for more robust references that don't change if the file is moved or renamed.
Revision: A specific version of a file, allowing you to share an older state of a document.
Namespace Relative Path: A path relative to a specific namespace, useful in team environments.

2. The `settings` Parameter

The settings parameter is an object that contains various options to customize the shared link's behavior. These settings are crucial for managing access and security.

Setting	Description	Possible Values / Details
`audience`	Controls who can access the link.	`public`, `team`
`access`	Defines the type of access granted.	`viewer`, `editor` (for files), `viewer` (for folders)
`requested_visibility`	Determines the default visibility of the link.	`public`, `team_only`, `password`
`link_password`	A password string to protect the link if `requested_visibility` is `password`.	String (e.g., `"MySecurePass123"`)
`expires`	A timestamp specifying when the link should expire.	ISO 8601 formatted timestamp (e.g., `"2024-12-31T23:59:59Z"`)
`allow_download`	Whether viewers can download the file.	`true`, `false`

Note: Not all settings are applicable to every file type or visibility option.

Practical Example: Creating a Password-Protected Link

Let's illustrate how you might structure a request to create a password-protected shared link for a file. This conceptual example shows the JSON body you would send to the API.

{
    "path": "/Projects/MyImportantDocument.pdf",
    "settings": {
        "requested_visibility": {
            ".tag": "password"
        },
        "link_password": "SecurePassword123!",
        "expires": "2025-01-01T00:00:00Z",
        "access": {
            ".tag": "viewer"
        }
    }
}

In this example:

The shared link is for the file MyImportantDocument.pdf in the /Projects folder.
It requires a password, "SecurePassword123!", for access.
The link will expire on January 1, 2025.
Users accessing the link will only have viewer permissions.

Steps to Implement Shared Link Creation

Authenticate Your Application: Obtain an access token with the necessary permissions (e.g., files.metadata.read, sharing.write).
Identify the Target File: Determine the path (file path, ID, or revision) of the file you want to share.
Define Link Settings: Decide on the desired requested_visibility, link_password (if applicable), expires (if applicable), and access level.
Make the API Call: Send a POST request to https://api.dropboxapi.com/2/sharing/create_shared_link_with_settings with your access token in the Authorization header and the JSON request body containing path and settings.
Process the Response: The API will return a response containing details about the newly created shared link, including its url.

Managing Existing Shared Links

Once a shared link is created, you can also manage it using other Dropbox API endpoints:

/sharing/list_shared_links: Retrieve a list of all shared links for your account or specific files.
/sharing/revoke_shared_link: Disable a shared link, making it inaccessible.
/sharing/update_shared_link_settings: Modify the settings of an existing shared link, such as changing its visibility or adding an expiration date.

By leveraging these endpoints, you can gain full programmatic control over how files are shared from your Dropbox account.

[[Dropbox API Sharing]]