Share links
A share link gives people outside your application (no account, no token) access to one file or one folder. This page explains how links are made, what they allow and how they end. It is for backend developers and administrators.
Creating a link
Section titled “Creating a link”POST P/files/:file_id/shares and POST P/folders/:folder_id/shares need share on the item and take:
| Field | Meaning |
|---|---|
actions |
["view"], or ["view", "download"] |
expires_at |
When the link ends. Default 7 days, at most the application’s share_link_max_days |
password |
Optional. The link asks for it before anything is shown |
max_downloads |
Optional. Counted per download |
label |
Your own note, shown in the console |
The answer holds token and url once: the service keeps only a hash of the token and cannot show it again. The URL is https://files.centralcodestation.com/s/<token> (the Files console’s share page), or your own host when the application sets share_base_url. A folder link covers the folder’s subtree as it is when someone opens it.
Share links must be on for the application and the tenant (share_links_disabled). Inside an application-managed folder only the application’s backend creates links; people get folder_managed.
What the link allows
Section titled “What the link allows”The public routes need no token and are rate limited per IP address (60 per minute):
| Route | Answers |
|---|---|
GET /shares/:token |
The target’s name, kind, size and renditions, the allowed actions, password_required, expires_at, and for a folder its listing |
POST /shares/:token/download |
{ url, expires_at }: a download URL living 5 minutes, with password, and file_id for a file inside a shared folder |
A link never grants any other API access. A wrong password answers share_password_invalid; 3 per minute attempts are allowed per address. A missing one answers share_password_required.
How a link ends
Section titled “How a link ends”| Cause | Answer |
|---|---|
Revoked (DELETE P/shares/:share_id), expired, its target trashed or quarantined, or, for a link a person made, its target now inside an application-managed folder |
410 share_gone |
max_downloads reached |
410 share_limit_reached |
The creator, a holder of share on the target, or files.manage may revoke a link. Every opening is audited (share.accessed, with the IP address), and so is every wrong password.
Listing links
Section titled “Listing links”| Route | Lists |
|---|---|
GET P/files/:file_id/shares, GET P/folders/:folder_id/shares |
The item’s links (without tokens): every link with share, otherwise the caller’s own |
GET P/shares |
The application’s links: every link with files.manage; otherwise the caller’s own. created_by filters |
Each link shows its access_count, last_accessed_at and download count.