Blob SDK: share links

Create, list and revoke Blob Storage share links with @squarecloud/blob, with expiration, download limits and passwords, and compare them with downloadUrl().

A share is a link to one object that can expire, be revoked, cap the number of downloads and, on Pro and Enterprise, ask for a password. See Links and sharing for how the links behave.

Examples use the blob client from Creating the client.

Share or downloadUrl()?

	downloadUrl()	shares.create()
Public object	Permanent CDN URL (expires_at: null)	Redirects to the permanent public URL (see the warning below)
Private object	Temporary link, up to 24 hours	Share link, up to 30 days
Revocable	No	Yes, with shares.revoke()
Download limit	No	Yes, max_downloads
Password	No	Yes, Pro and Enterprise

Use downloadUrl() for short-lived links you hand out yourself, and a share when you need to take the link back or control who downloads it.

Creating a share

const share = await blob.shares.create(id, {
    expires_in: 86400,     // seconds, 60 to 2592000 (default 86400)
    max_downloads: 10,     // 1 to 10000
    password: "secret123", // 8 to 128 characters, Pro and Enterprise
});

console.log(share.url);

Option	Type	Description
expires_in	number	Link lifetime in seconds, 60 to 2592000 (30 days). Default 86400.
max_downloads	number	1 to 10000.
password	string	8 to 128 characters. Pro and Enterprise; other plans get UPGRADE_REQUIRED.

The result has id, url, expires_at, max_downloads, password (whether one is set), object and object_is_public.

If object_is_public is true, the share link redirects to the object’s permanent public URL: the password, download limit and expiration protect nothing, because the file stays reachable at that URL. Make the object private first, then share it:

const [result] = await blob.update(id, { private: true });
if (result.ok) {
    id = result.id; // the id changes
    const share = await blob.shares.create(id, { max_downloads: 1 });
}

Listing shares

const shares = await blob.shares.list();

Returns an array of shares, each with id, url, object, expires_at, remaining_downloads, password and created_at.

Revoking a share

await blob.shares.revoke(share.id);

The link stops working. revoke() resolves to nothing, and revoking a share that does not exist fails with SHARE_NOT_FOUND.

Deleting, moving or renaming the object, or changing its visibility, also breaks its share links: they point to the old id. Create new shares for the new id.

shares.create() and shares.revoke() get a single attempt. Only shares.list(), a read, is retried.

API reference: Create Share, List Shares, Delete Share.

Next steps

Rules and stats

Per-prefix rules and usage stats.

Links and sharing

How public URLs, download links and shares behave.