Box Developer Documentation
Log in

Create or Update Shared Link

Guides Shared Links Create or Update Shared Link
Edit this page

Create or Update Shared Link

Shared links may be created or directly for file, folder, or web link resources to generate a read-only URL to permit users with the appropriate access level to view the content.

You may only have one active shared link for a file, folder, or web link at any time.

At minimum the information needed to create a shared link will be:

  • The type of resource, either a file, folder, or web link.
  • The ID of that resource.

Optionally when creating a shared link the following may be specified:

  • The access level, which may be one of:
    • open: A public shared link. Anyone with the link may access the link.
    • company: Anyone within your enterprise may access the link.
    • collaborators: Anyone collaborated on the content may access the link.
  • An expiration time when the shared link will automatically disable.
  • A password required to access the resource.

If an access level is not specified when creating a shared link it will use the default access level specified by the enterprise admin.

Create or Update Shared Link for File

To create a shared link on a file, specify the ID of the file with any optional shared link parameters.

cURL
curl -i -X PUT "https://api.box.com/2.0/files/32423234?fields=shared_link" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "shared_link": {
         "access": "open",
         "password": "mypassword",
         "unshared_at": "2012-12-12T10:53:43-08:00",
         "permissions": {
           "can_download": false
         }
       }
     }'
TypeScript Gen
await client.sharedLinksFiles.addShareLinkToFile(
  fileId,
  {
    sharedLink: {
      access: 'open' as AddShareLinkToFileRequestBodySharedLinkAccessField,
      password: 'Secret123@',
    } satisfies AddShareLinkToFileRequestBodySharedLinkField,
  } satisfies AddShareLinkToFileRequestBody,
  { fields: 'shared_link' } satisfies AddShareLinkToFileQueryParams,
);
Python Gen
client.shared_links_files.add_share_link_to_file(
    file_id,
    "shared_link",
    shared_link=AddShareLinkToFileSharedLink(
        access=AddShareLinkToFileSharedLinkAccessField.OPEN, password="Secret123@"
    ),
)
.NET Gen
await client.SharedLinksFiles.AddShareLinkToFileAsync(fileId: fileId, requestBody: new AddShareLinkToFileRequestBody() { SharedLink = new AddShareLinkToFileRequestBodySharedLinkField() { Access = AddShareLinkToFileRequestBodySharedLinkAccessField.Open, Password = "Secret123@" } }, queryParams: new AddShareLinkToFileQueryParams(fields: "shared_link"));
Swift Gen (Beta)
try await client.sharedLinksFiles.addShareLinkToFile(fileId: fileId, requestBody: AddShareLinkToFileRequestBody(sharedLink: AddShareLinkToFileRequestBodySharedLinkField(access: AddShareLinkToFileRequestBodySharedLinkAccessField.open, password: "Secret123@")), queryParams: AddShareLinkToFileQueryParams(fields: "shared_link"))
Java
// Optionally we can calculate and set the date when shared link will automatically be disabled
final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
long unsharedTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS;
Date unsharedDate = new Date(unsharedTimestamp);

BoxFile file = new BoxFile(api, "id");
BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest()
    .access(OPEN)
    .permissions(true, true)
    .unsharedDate(unsharedDate);
BoxSharedLink sharedLink = file.createSharedLink(sharedLinkRequest);
Python
file_id = '11111'

url = client.file(file_id).get_shared_link(access='open', allow_download=True, allow_edit=True)
print(f'The file shared link URL is: {url}')
.NET
string fileId = "11111";
var sharedLinkParams = new BoxSharedLinkRequest()
{
    Access = BoxSharedLinkAccessType.open,
    Permissions = new BoxPermissionsRequest
    {
        Download = true,
        Edit = true
    }
};
BoxFile file = client.FilesManager.CreateSharedLinkAsync(fileId, sharedLinkParams);
string sharedLinkUrl = file.SharedLink.Url;
Node
client.files.update('12345', {
  shared_link: {
    access: "open",
    password: "do-not-use-this-password", 
    unshared_at: "2022-12-12T10:53:43-08:00",
    vanity_name: "my-shared-link",
    permissions: {
	  can_view: true,
	  can_download: true,
	  can_edit: true
    }
  }
}).then(file => {
  // ...
})
iOS
client.files.setSharedLink(
    forFile: "11111", 
    access: .open, 
    canDownload: true, 
    canEdit: true
) { (result: Result<SharedLink, BoxSDKError>) in
    guard case let .success(sharedLink) = result else {
        print("Error setting file shared link")
        return
    }

    print("File shared link URL is \(sharedLink.url), with \(sharedLink.access) access")
}

Create or Update Shared Link for Folder

To create a shared link on a folder, specify the ID of the folder with any optional shared link parameters.

cURL
curl -i -X PUT "https://api.box.com/2.0/folders/32423234?fields=shared_link" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "shared_link": {
         "access": "open",
         "password": "mypassword",
         "unshared_at": "2012-12-12T10:53:43-08:00",
         "permissions": {
           "can_download": false
         }
       }
     }'
TypeScript Gen
await client.sharedLinksFolders.addShareLinkToFolder(
  folder.id,
  {
    sharedLink: {
      access: 'open' as AddShareLinkToFolderRequestBodySharedLinkAccessField,
      password: 'Secret123@',
    } satisfies AddShareLinkToFolderRequestBodySharedLinkField,
  } satisfies AddShareLinkToFolderRequestBody,
  { fields: 'shared_link' } satisfies AddShareLinkToFolderQueryParams,
);
Python Gen
client.shared_links_folders.add_share_link_to_folder(
    folder.id,
    "shared_link",
    shared_link=AddShareLinkToFolderSharedLink(
        access=AddShareLinkToFolderSharedLinkAccessField.OPEN, password="Secret123@"
    ),
)
.NET Gen
await client.SharedLinksFolders.AddShareLinkToFolderAsync(folderId: folder.Id, requestBody: new AddShareLinkToFolderRequestBody() { SharedLink = new AddShareLinkToFolderRequestBodySharedLinkField() { Access = AddShareLinkToFolderRequestBodySharedLinkAccessField.Open, Password = "Secret123@" } }, queryParams: new AddShareLinkToFolderQueryParams(fields: "shared_link"));
Swift Gen (Beta)
try await client.sharedLinksFolders.addShareLinkToFolder(folderId: folder.id, requestBody: AddShareLinkToFolderRequestBody(sharedLink: AddShareLinkToFolderRequestBodySharedLinkField(access: AddShareLinkToFolderRequestBodySharedLinkAccessField.open, password: "Secret123@")), queryParams: AddShareLinkToFolderQueryParams(fields: "shared_link"))
Java
// Optionally we can calculate and set the date when shared link will automatically be disabled
final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
long unsharedTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS;
Date unsharedDate = new Date(unsharedTimestamp);

BoxFolder folder = new BoxFolder(api, "id");
BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest()
        .access(OPEN)
        .permissions(true, true)
        .unsharedDate(unsharedDate);
BoxSharedLink sharedLink = folder.createSharedLink(sharedLinkRequest);
Python
folder_id = '11111'

url = client.folder(folder_id).get_shared_link(access='open', allow_download=False)
print(f'The folder shared link URL is: {url}')
.NET
var sharedLinkParams = new BoxSharedLinkRequest()
{
    Access = BoxSharedLinkAccessType.open
};
BoxFolder folder = await client.FoldersManager.CreateSharedLinkAsync("11111", sharedLinkParams);
string sharedLinkUrl = folder.SharedLink.Url;
Node
client.folders.update('12345', {
  shared_link: {
    access: "open",
    password: "do-not-use-this-password",
    unshared_at: "2022-12-12T10:53:43-08:00",
    vanity_name: "my-shared-link",
    permissions: {
      can_view: true,
      can_download: true
    }
  }
}).then(folder => {
  // ...
})
iOS
client.folders.setSharedLink(forFolder: "11111", access: .open) { (result: Result<SharedLink, BoxSDKError>) in
    guard case let .success(sharedLink) = result else {
        print("Error setting folder shared link")
        return
    }

    print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access")
}

Create or Update Shared Link for Web Link

To create a shared link on a web link, specify the ID of the web link with any optional shared link parameters.

cURL
curl -i -X PUT "https://api.box.com/2.0/web_links/32423234?fields=shared_link" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "shared_link": {
         "access": "open",
         "password": "mypassword",
         "unshared_at": "2012-12-12T10:53:43-08:00",
         "permissions": {
           "can_download": false
         }
       }
     }'
TypeScript Gen
await client.sharedLinksWebLinks.addShareLinkToWebLink(
  webLinkId,
  {
    sharedLink: {
      access: 'open' as AddShareLinkToWebLinkRequestBodySharedLinkAccessField,
      password: 'Secret123@',
    } satisfies AddShareLinkToWebLinkRequestBodySharedLinkField,
  } satisfies AddShareLinkToWebLinkRequestBody,
  { fields: 'shared_link' } satisfies AddShareLinkToWebLinkQueryParams,
);
Python Gen
client.shared_links_web_links.add_share_link_to_web_link(
    web_link_id,
    "shared_link",
    shared_link=AddShareLinkToWebLinkSharedLink(
        access=AddShareLinkToWebLinkSharedLinkAccessField.OPEN, password="Secret123@"
    ),
)
.NET Gen
await client.SharedLinksWebLinks.AddShareLinkToWebLinkAsync(webLinkId: webLinkId, requestBody: new AddShareLinkToWebLinkRequestBody() { SharedLink = new AddShareLinkToWebLinkRequestBodySharedLinkField() { Access = AddShareLinkToWebLinkRequestBodySharedLinkAccessField.Open, Password = "Secret123@" } }, queryParams: new AddShareLinkToWebLinkQueryParams(fields: "shared_link"));
Swift Gen (Beta)
try await client.sharedLinksWebLinks.addShareLinkToWebLink(webLinkId: webLinkId, requestBody: AddShareLinkToWebLinkRequestBody(sharedLink: AddShareLinkToWebLinkRequestBodySharedLinkField(access: AddShareLinkToWebLinkRequestBodySharedLinkAccessField.open, password: "Secret123@")), queryParams: AddShareLinkToWebLinkQueryParams(fields: "shared_link"))
Python
url = client.web_link('12345').get_shared_link(access='open')
print(f'The web link shared link URL is: {url}')
.NET
string webLinkId = "11111";
var sharedLinkParams = new BoxSharedLinkRequest()
{
    Access = BoxSharedLinkAccessType.open
};
BoxWebLink link = client.WebLinksManager
    .CreateSharedLinkAsync(webLinkId, sharedLinkParams);
string sharedLinkUrl = link.SharedLink.Url;
iOS
client.webLinks.setSharedLink(forWebLink: "11111", access: .open) { (result: Result<SharedLink, BoxSDKError>) in
    guard case let .success(sharedLink) = result else {
        print("Error setting weblink shared link")
        return
    }

    print("WebLink shared link URL is \(sharedLink.url), with \(sharedLink.access) access")
}