Shared links (IRPCSharedLinks)
Creates and manages shared links to files for people outside the vault.
| gRPC service | MFiles.IRPCSharedLinks |
|---|---|
| Book and level | Vault API, standard |
| Methods | 15 |
| Proto file | mfiles/IRPCSharedLinks.proto |
Overview
Creates and manages shared links: links that give people outside the vault access to one file of a document. A link is identified by its access key, a 64-character random string that the server generates. Anyone who has the access key and the vault GUID can use the link through IRPCSharedLinksPublic without logging in, so treat access keys as secrets.
Link types (SharedLinkType):
SHARED_LINK_TYPE_READ_ONLY: a public download link. Anyone with the key can download the file. Points to a specific checked-in object version.SHARED_LINK_TYPE_EXTERNAL: an external link, shared with named visitors (recipients) that each have an expiration time and access type, or with anyone who has the link (is_anyone_access_granted). Points to the latest version.SHARED_LINK_TYPE_VISITOR: the older form of a link shared with named visitors. Points to the latest version.SHARED_LINK_TYPE_CO_AUTHORING,SHARED_LINK_TYPE_WOPIREADONLY,SHARED_LINK_TYPE_WOPIEDIT: internal links for co-authoring and Office for the web, used by M-Files clients.
Typical flows:
- Public download link:
CreateSharedLink with
SHARED_LINK_TYPE_READ_ONLY; list with GetSharedLinks or GetSharedLinksByObject; remove with DeleteSharedLink. - External link: check
GetExternalSharingSettings, create
the link with
SHARED_LINK_TYPE_EXTERNAL, add visitors with AddSharedLinkRecipients, and manage them with GetSharedLinkRecipients, SetSharedLinkRecipients and RemoveSharedLinkRecipients. Grant or revoke access for anyone with the link with SetSharedLinks. List an object's external links with GetExternalLinks.
Prerequisites: sharing must be enabled on the server and in the vault; otherwise the methods fail with "Access denied." (except for the internal link types). Read-only links, and external links open to anyone, also need the vault setting that allows sharing with anyone who has the link. Anonymous sessions cannot use this service.
Times. An unset expiration time means "never expires"; the server returns it as 1601-01-01T00:00:00Z. A recipient added without an expiration time is returned with 1753-01-01T00:00:00Z.
Errors. An unknown, deleted or expired access key fails with "The link is either expired or invalid.".
Methods
| Method | Summary | Facts |
|---|---|---|
| AddSharedLinkRecipients | Adds visitors (email recipients) to an external or visitor link and returns all its recipients. | write session or assertion returns metadata structure version |
| CreateSharedLink | Creates a shared link to one file of an object and returns it with its new access key. | write session or assertion returns metadata structure version |
| DeleteSharedLink | Deletes a shared link, so that its access key stops working. | write session or assertion returns metadata structure version |
| GetExternalLinks | Lists the external links of an object. | write session or assertion returns metadata structure version |
| GetExternalSharingSettings | Tells whether sharing is enabled in the vault and what the caller may do with external links. | write session or assertion returns metadata structure version |
| GetSharedLink | Gets one shared link by its access key. | write session or assertion returns metadata structure version |
| GetSharedLinkRecipients | Lists the visitors (email recipients) of an external or visitor link. | write session or assertion returns metadata structure version |
| GetSharedLinks | Lists the shared links that the caller created, or all links for users who can see all objects. | write session or assertion returns metadata structure version |
| GetSharedLinksByObject | Lists the shared links to one object. | write session or assertion returns metadata structure version |
| GetWOPILock | Not supported: always fails with "Not implemented.". | write no session |
| RemoveSharedLinkRecipients | Removes visitors from an external or visitor link. | write session or assertion |
| RemoveWOPILock | Not supported: always fails with "Not implemented.". | write no session |
| SetSharedLinkRecipients | Updates the expiration time and access type of visitors of external links. | write session or assertion returns metadata structure version |
| SetSharedLinks | Updates the access type of shared links, and grants or revokes access for anyone who has the link. | write session or assertion returns metadata structure version |
| SetWOPILock | Not supported: always fails with "Not implemented.". | write no session |