File Sharing

Create, inspect, and revoke shares—with passwords, expiry, download limits, and how ticket allowance actually works.

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—don't invent a /s/ link or place the token in a public index. A password-free link is itself an access credential. A password requirement isn't 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. For 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 doesn't 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 the password in the body when required. Successful ticket issuance immediately increments the share's downloadCount.

This means maxDownloads limits successfully issued tickets, not completed local downloads. A later network failure may still have consumed an allowance. Don't 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 isn't 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 doesn't guarantee revoking an already issued, still-valid grant, and can't delete a recipient's saved copy. If settings need to change or the token was lost, the owner can create a suitable new share and revoke the old record.