Sharing

Sharing a folder

The API provides the ability to share a folder. To share a folder, issue the following POST request:

POST /api/folders/{folderId}/share

Where:

  • folderId: the ID of the folder to share

With the following body:

{
    "ExpireStyle" : {days|hours|minutes|date|never},
    "ExpiresOn" : <datetime>,
    "ExpirationValue" : <integer>,
    "PinRequired" : {true|false},
    "AccessCodeRequired" : {true|false},
    "Recipients" : [""],
    "EmailRecipientsCc": [""],
    "Password" : "",
    "AllowView" : {true|false},
    "AllowDownload" : {true|false},
    "AllowUpload" : {true|false},
    "NotifyRecipients": {true|false},
    "CustomEmailHeader": "",
    "CustomEmailText":"",
    "ShareType": {Content|Template}
}
  • ExpireStyle: this is a string indicating the type of expiration used
  • days: the link expires after N days - populate ExpirationValue with the days if this option is selected
  • hours: the link expires after N hours - populate ExpirationValue with the hours if this option is selected
  • minutes: the link expires after N minutes - populate ExpirationValue with the minutes if this option is selected
  • date: the link expires on a given date - populate ExpiresOn with the date if this option is selected
  • never: the link never expires
  • ExpiresOn: valid and required when ExpireStyle is set to date; ignored/optional otherwise
  • ExpirationValue: valid and required when ExpireStyle is set to days, hours, or minutes; ignored/optional otherwise
  • PinRequired: This option is being deprecated - use AccessCodeRequired instead
  • AccessCodeRequired: if provided, a boolean that specifies whether the share should require an access code for viewing - see Email access code below for more details
  • Recipients: an array of email addresses that will receive an email message containing a link to the share
  • EmailRecipientsCc: an array of email addresses that will be cc'ed on the email notification for the share - valid when Recipients is populated and NotifyRecipients is true
  • Password: if provided, this is the password required to view this link - note that this password must adhere to the password policy for the deployment
  • AllowView: if true, the documents in this folder can be viewed
  • AllowDownload: if true, the documents in this folder can be downloaded
  • AllowUpload: if true, the recipient of the link can add documents to the folder
  • NotifyRecipients: defaults to true; if false, does not send an email to the recipients - web links for recipients can be retrieved with an endpoint below
  • CustomEmailHeader: an optional subject line included in the email for the share - valid when Recipients is populated and NotifyRecipients is true
  • CustomEmailText: an optional message included in the email for the share - valid when Recipients is populated and NotifyRecipients is true
  • ShareType: a string specifying the type of folder share, which determines the UI the end user will see in the New Link Experience Beta feature. Only Content and Template are currently supported, with a default of Content - see Guided Upload Folder Shares below for more details on Template shares

Upon successful creation, an HTTP 200 OK status code is returned with a response body like the following:

{
    "ShareId" : 1,
    "FolderId" : 1,
    "ReferenceString" : "ABCDEFabcdef__",
    "Status" : "Active",
    "ShareType" : "Content",
    "Link" : "https://app.sharebase.com/folder/920/share/ABCDEFabcdef__", // obsolete, replaced by Links.WebUri
    "Links" : {
        "WebUri" : "https://app.sharebase.com/folder/920/share/ABCDEFabcdef__", // not valid for access code shares, see below
        "Self" : "https://app.sharebase.com/sharebaseapi/api/folders/1/share/1"
    }
}

Where:

  • ShareId: a unique identifier representing the share
  • FolderId: the unique identifier for the folder
  • ReferenceString: a unique string representing the share
  • Status: a value whether the share is Active or Pending and cannot be accessed for preparation in Sharing as a Service (ShaaS)
  • ShareType: the type of share the folder share is, content unless specified otherwise.
  • Links:
  • WebUri: a hyperlink to the share - This value can be embedded in an email or a web page

Note that if a share is provided with false for all of the following parameters: AllowView, AllowDownload, and AllowUpload, an HTTP 400 Bad Request will be returned and the share will not be created.

Shares that do not have expirations specified will return an HTTP 400 Bad Request, stating that the expiration was not specified. This is the case when ExpireStyle is set to "date" and a value for ExpiresOn is not provided, and when ExpireStyle is set to "days", "hours", or "minutes" and a value for ExpirationValue is not provided.

In addition, shares that have expirations that are not set in the future will return an HTTP 400 Bad Request that states that the expiration needs to be in the future.

If the specified ShareType is not Content OR Template, an HTTP 400 Bad Request will be returned.

Another HTTP 400 Bad Request will be returned if the expiration violates a maximum link expiration duration setting.

Guided Upload Folder Shares

NOTE: The following functionality can only be taken advantage of when the New Link Experience & Dynamic Branding features are turned on. Please contact your account manager.

When a folder share is created with a ShareType of Template via the HTTP POST /api/folders/{folderId}/share endpoint, the share will be generated as a guided upload folder share. Shares generated this way provide a curated UI tailored to the needs of the user.

Warning

Please note, you must enable both AllowView and AllowUpload for Template folder shares, so that users can see the UI and upload content.

The end user will be presented with a dialog corresponding to the library brand's prompt that looks similar to the following:

LibraryPrompt

After confirming they've read the prompt, the user will be presented with interactive buttons with names corresponding to sub folders within the folder share. These expose the ability to upload directly to that folder, meaning the folder name can guide the end user exactly what they need to upload. Once the user uploads a document to the folder, a check box will appear along with a badge stating the number of documents in the folder. The UI will look similar to the following:

TemplateUI

For more information on setting up a brand to accompany this feature, please refer to our branding documentation.

Sharing a document

The API provides the ability to share a document. To share a document, issue the following POST request:

POST /api/documents/{documentId}/share

Where:

  • documentId: the ID of the document to share

With the following body:

{
    "ExpireStyle" : {days|hours|minutes|date|never},
    "ExpiresOn" : <datetime>,
    "ExpirationValue" : <integer>,
    "PinRequired" : {true|false},
    "AccessCodeRequired" : {true|false},
    "Recipients" : [""],
    "EmailRecipientsCc": [""],
    "Password" : "",
    "AllowView" : {true|false},
    "AllowDownload" : {true|false},
    "AllowEdit" : {true|false},
    "NotifyRecipients": {true|false},
    "CustomEmailHeader": "",
    "CustomEmailText":""
}
  • ExpireStyle: this is a string indicating the type of expiration used
  • days: the link expires after N days - populate ExpirationValue with the days if this option is selected
  • hours: the link expires after N hours - populate ExpirationValue with the hours if this option is selected
  • minutes: the link expires after N minutes - populate ExpirationValue with the minutes if this option is selected
  • date: the link expires on a given date - populate ExpiresOn with the date if this option is selected
  • never: the link never expires
  • ExpiresOn: valid and required when ExpireStyle is set to date; ignored/optional otherwise
  • ExpirationValue: valid and required when ExpireStyle is set to days, hours, or minutes; ignored/optional otherwise
  • PinRequired: This option is being deprecated - use AccessCodeRequired instead
  • AccessCodeRequired: if provided, a boolean that specifies whether the share should require an access code for viewing - see Email access code below for more details
  • Recipients: an array of email addresses that will receive an email message containing a link to the share
  • EmailRecipientsCc: an array of email addresses that will be cc'ed on the email notification for the share - valid when Recipients is populated and NotifyRecipients is true
  • Password: if provided, the password required to view this link - note that this password must adhere to the password policy for the deployment
  • AllowView: if true, the document can be viewed
  • AllowDownload: if true, the document can be downloaded
  • AllowEdit: if true, the document can be revised
  • NotifyRecipients: defaults to true; if false, does not send an email to the recipients - web links for recipients can be retrieved with an endpoint below
  • CustomEmailHeader: an optional subject line included in the email for the share - valid when Recipients is populated and NotifyRecipients is true
  • CustomEmailText: an optional message included in the email for the share - valid when Recipients is populated and NotifyRecipients is true

Upon successful creation, an HTTP 200 OK status code is returned with a response body like the following:

{
    "ShareId" : 1,
    "DocumentId" : 920,
    "Links" : {
        "WebUri" : "https://app.sharebase.com/document/920/share/{ReferenceString}", // not valid for access code shares, see below
        "Self" : "https://app.sharebase.com/sharebaseapi/api/documents/920/share/1"
    }
}

Where:

  • ShareId: a unique identifier representing the share
  • DocumentId: the unique identifier for the document
  • Links:
  • WebUri: a hyperlink to the shared document - this value can be embedded in an email or a web page
    • ReferenceString: a unique string representing the share

Note that if a share is provided with false for all of the following parameters: AllowView, AllowDownload, and AllowUpload, an HTTP 400 Bad Request will be returned and the share will not be created;

Shares that do not have expirations specified will return an HTTP 400 Bad Request, stating that the expiration was not specified. This is the case when ExpireStyle is set to "date" and a value for ExpiresOn is not provided, and when ExpireStyle is set to "days", "hours", or "minutes" and a value for ExpirationValue is not provided.

In addition, shares that have expirations that are not set in the future will return an HTTP 400 Bad Request that states that the expiration needs to be in the future.

Another HTTP 400 Bad Request will be returned if the expiration violates a maximum link expiration duration setting.

Adding security to shares

To provide a second level of authentication for shares and to prevent indiscriminate sharing of links, an option for emailing an access code or creating a custom password can be used when creating shares.

If no security option is used, then the share can be accessed by anyone who has the link.

Email access code

Enabling the email access code option requires a recipient to enter a uniquely generated access code to view a share. To enable this option, you must set AccessCodeRequired to true when creating the share. Additionally, the Recipients array must have at least one email address configured. If no Recipients are provided, an HTTP 400 Bad Request will be returned. If NotifyRecipients is true (the default value), ShareBase will send an email to each recipient with a unique link for accessing the share. If NotifyRecipients is false, the links can be retrieved with the endpoint below. These links are specific to the recipient, and must be shared if sending the links manually.

For a recipient, accessing the share will be done as follows. First, the recipient will receive an email which contains a link (sent from ShareBase if NotifyRecipients is true). Next, when the recipient clicks this link they will be taken to a page that requires a password, and a new email with a uniquely generated password will automatically be sent to the recipient's email address. Finally, the recipient will enter this password and will then be given access to the share.

Using this flow means that anyone accessing a share set-up with email access code must have access to the inbox of the original recipient. This makes the link inaccessible to anyone who lacks access to the recipient's inbox.

Email access codes are not sent to cc'ed recipients (specified using EmailRecipientsCc). If a cc'ed recipient attempts to access a share protected by an email access code, the email access code is sent to the recipient (from Recipients) for whom the link was created. Therefore, cc'ed recipients are not able to access the shared content using the link if a share was created using email access code security.

Creating a custom password

Adding a custom password requires a recipient to enter a set password to access the share. To enable this option, provide a password for the Password option. When creating a password for the share, the deployment's password policies will be enforced, for example, requiring a specific length or requiring special characters. If the password does not adhere to the password policy an HTTP 400 Bad Request will be returned. The password will not be sent by ShareBase, therefore the password will need to be communicated to users who need to access the share by some other means.

Note that if a share is configured with both Password and a AccessCodeRequired being set, an HTTP 400 Bad Request will be returned and the share will not be created.

Retrieving recipients for a share

The API provides the ability to get recipients for an existing share, including the unique web link per recipient.

To get the recipients, issue the following GET request:

GET /api/folders/{folderId}/shares/{shareId}/recipients

GET /api/documents/{documentId}/shares/{shareId}/recipients

Where:

  • folderId: the ID of the folder with the share
  • documentId: the ID of the document with the share
  • shareId: the ID of the share

Upon successful creation, an HTTP 200 OK status code is returned with a response body like the following:

[
    {
        "Recipient": "recipient@example.com",
        "WebUri": "https://app.sharebase.com/folder/20444/share/1-ZfOVBurgs4jkSCEA0TQ--l31wCPo"
    }
]

[
    {
        "Recipient": "recipient@example.com",
        "WebUri": "https://app.sharebase.com/document/3991/share/1-M00FSnnIoQfIbOpGMfDQNtqdb20?recipient=10332"
    },
    {
        "Recipient": "share@recipient.com",
        "WebUri": "https://app.sharebase.com/document/3991/share/1-M00FSnnIoQfIbOpGMfDQNtqdb20?recipient=10333"
    }
]

Note, only the share creator can retrieve the recipients. Otherwise, there will be an HTTP 403 Forbidden response. An HTTP 404 Not Found response will be returned if the specified share does not exist.

Also, as mentioned in the access code section, these links are only usable by the recipient, because the required access codes are sent to their email.

Revoking a share

The API provides the ability to revoke a share on a folder or document by issuing the following DELETE request:

DELETE /api/folders/{folderId}/share/{shareId}

DELETE /api/documents/{documentId}/{shareId}

Where:

  • folderId: the ID of the folder with the share
  • documentId: the ID of the document with the share
  • shareId: the ID of the share to be revoked

Alternatively, if you have a reference to a folder or document share you can simply issue a DELETE on the Self property of the Links embedded property.