File Sharing

Create, inspect and revoke shares; understand passwords, expiry, limits and download tickets.

Shares and publications differ

A share uses a random token and can require a password, expire or limit ticket issuance. The active app has no dedicated share-receiving route. Recipients need an operator-provided client that exchanges the token for a ticket; do not invent a /s/ link or place the token in a public index. A password-free link is itself an access credential. A password requirement is not end-to-end encryption.

The current account page has no share-creation or management panel. Owners use authenticated APIs for management; receiving requires an API client too. To enter the anonymous catalogue, see Publications.

Create and retain the result

Call POST /api/v1/files/{fileId}/shares with {} or these optional fields:

| Field | Rule | | --- | --- | | password | Nonempty, at most 1024 UTF-8 bytes; omit for no password | | expiresAt | A future canonical UTC ISO timestamp, shaped YYYY-MM-DDTHH:mm:ss.sssZ | | maxDownloads | Integer from 1 to 2147483647; omit to leave this limit unset |

Success returns 201. The raw token appears only in the creation response; the server stores its digest. Listing shares does not recover a lost token. Retain the result securely and send it only to intended recipients, never to public logs.

GET /api/v1/files/{fileId}/shares lists records. Revoke using the record's shareId with POST /api/v1/shares/{shareId}/revoke; success returns 204. shareId and the recipient-link token are different values.

Receiving and consuming the allowance

The recipient uses the operator-provided client and supplies a password if required. The client requests POST /api/v1/shares/{token}/download-ticket, with password in the body when required. Successful ticket issuance immediately increments the share's downloadCount.

Thus maxDownloads limits **successfully issued tickets, not completed local downloads**. A later network failure may still have consumed an allowance. Do not prefetch or automatically repeat ticket requests to probe availability.

The resulting downloadGrant lasts 60 seconds and is single-use. Request the returned objectKey using that grant. A share selects the file's current version at ticket issuance; a long-lived share is not a pinned historical-version link.

Unavailable and revoked shares

Wrong password, expiry, exhaustion, revocation and unavailable files generally produce the same 404 share unavailable, deliberately withholding detail. Ask the sender to check rather than assuming the file was deleted.

Revocation prevents new tickets. It does not guarantee revoking an already issued, still-valid grant, and cannot delete a recipient's saved copy. If settings must change or the token was lost, the owner can create a suitable new share and revoke the old record.