Expiring links

Send someone a link to a file, or to a resized image, that stops working at a time you choose. You can turn it off before then, and see how often it was opened.

How it works

An expiring link is a short URL like

https://api.fileboy.io/links/q7Hc2mX9pLwR4tYvB8nK1sDf

. Fileboy stores it with the file it opens, what it opens (the file, a download or one image transform) and when it stops working. Every time someone opens it, Fileboy looks it up, so:

it stops at the time you chose, to the second;
turning it off (revoking it) works at once, and only for that link. Your other links and signed URLs keep working;
deleting the file stops every link to it;
it doesn't show the file's id, so the person you send it to can't work out the file's own URL from it.

The query string is ignored. Someone who has a link to a 400 px thumbnail can't change it into the full image or a download.

Make one

In the dashboard, open the file and go to Share & embed. Pick 1 hour, 1 day, 7 days, 30 days or a date and time. Then choose what the link opens: the file, a download (with an optional file name) or, for images, a resized image with a transform you can preview. Add a note to remind yourself who it's for, then copy the link. The Image builder tab can hand the transform you built straight to the form.

From your server it needs the private key. Give

expiresIn

(seconds) or

expiresAt

(a time with a time zone):

Expiring links

// on your server, with the private key
const link = await fileboy.createFileLink(id, { expiresIn: 7 * 24 * 3600, note: "for the auditors" })
// link.url: https://api.fileboy.io/links/q7Hc2mX9pLwR4tYvB8nK1sDf

// an image transform, as a download, until a set time
await fileboy.createFileLink(id, {
  expiresAt: new Date("2026-12-01T09:00:00Z"),
  transform: "resize:1600x_;format:webp",
  download: true,
  filename: "poster.webp",
})

const { data } = await fileboy.listFileLinks(id, { status: "active" }) // with useCount
await fileboy.revokeFileLink(id, link.id) // stops working now

# on your server, with the private key
link = fileboy.create_file_link(id, expires_in: 7 * 24 * 3600, note: "for the auditors")
link.url # => "https://api.fileboy.io/links/q7Hc2mX9pLwR4tYvB8nK1sDf"

fileboy.create_file_link(id, expires_at: Time.utc(2026, 12, 1, 9),
                             transform: "resize:1600x_;format:webp", download: true)

fileboy.list_file_links(id, status: "active").items.map(&:use_count)
fileboy.revoke_file_link(id, link.id) # stops working now

# on your server, with the private key
link = client.create_file_link(file_id, expires_in=7 * 24 * 3600, note="for the auditors")
link.url  # "https://api.fileboy.io/links/q7Hc2mX9pLwR4tYvB8nK1sDf"

client.create_file_link(file_id, expires_at=datetime(2026, 12, 1, 9, tzinfo=timezone.utc),
                        transform="resize:1600x_;format:webp", download=True)

[l.use_count for l in client.list_file_links(file_id, status="active")]
client.revoke_file_link(file_id, link.id)  # stops working now

// on your server, with the private key
$link = $fileboy->createFileLink($id, expiresIn: 7 * 24 * 3600, note: 'for the auditors');
$link->url; // https://api.fileboy.io/links/q7Hc2mX9pLwR4tYvB8nK1sDf

$fileboy->createFileLink($id, expiresAt: new DateTimeImmutable('2026-12-01T09:00:00Z'),
    transform: 'resize:1600x_;format:webp', download: true);

$page = $fileboy->listFileLinks($id, ['status' => 'active']);
$fileboy->revokeFileLink($id, $link->id); // stops working now

curl -X POST https://api.fileboy.io/files/$FILE_ID/links \
  -H "Authorization: token YOUR_SIGNED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresIn": 604800, "note": "for the auditors"}'

curl -X DELETE https://api.fileboy.io/files/$FILE_ID/links/$LINK_ID \
  -H "Authorization: token YOUR_SIGNED_TOKEN"

The file can be given by id or by label. The answer has the link's

url

, its

status

(

active

expired

revoked

useCount

and

lastUsedAt

. See the management API for every field.

Public files and Signed URLs only

A link works whatever the file's read permission and whether or not the app requires signed URLs. It was made by someone allowed to read the file, so it grants what a signed URL with the same expiry would.

What it does not do is make a public file private. If the file is public, its own URL works for anyone who has it, before and after the link expires. The dashboard says so on a public file's Share tab.

To make expiring links the only way in, set the file to Signed URLs only (on its Settings tab), or require signed URLs for the whole app. Then its plain URLs answer 401, and the links you hand out are what people use.

Turn one off

On the file's Share tab, Turn off now next to the link, or

DELETE /files/{id}/links/{linkId}

. From then on the link answers

410 link_revoked

. Doing it twice is fine. A browser that already downloaded the file keeps its copy, and may show it from its own cache for up to five minutes.

What someone opening it gets

While it is active: the file or image, exactly as
```
/files/get
```
or
```
/images/get
```
would serve it. Seeking in audio and video works (
```
Range
```
), and
```
format:auto
```
picks the format the browser accepts.
After it expires:
```
410 link_expired
```
. Once it is turned off:
```
410 link_revoked
```
. A link that never existed, or whose file was deleted:
```
404 link_not_found
```
.

Responses are

Cache-Control: private

, so CDNs and shared caches never keep them, and browsers keep them for at most five minutes, never past the expiry. Links send

X-Robots-Tag: noindex

. Opening a link counts as a use when the read starts at the beginning of the file: a video player asking for the next part of the file, or a

HEAD

request, does not.

Limits

A link lasts from one minute to 365 days.
A file can have 100 active links. Expired and revoked ones don't count. Over that, making one answers
```
409 too_many_links
```
.
The transform is checked when the link is made (
```
400 invalid_transform
```
). Notes are up to 200 characters, file names up to 255.
Links are for files. A video's manifest and segments need signed URLs, which cover a whole video with one signature. Files that are part of a video, and image copies Fileboy made, can't have links.

Expiring links or signed URLs?

Both expire. They suit different jobs:

Expiring links are for links you hand to people: a contract for a client, a press kit for a week, a preview for a reviewer. They are stored, so you can list them, see if they were opened and turn one off. You can make them in the dashboard without writing code.
Signed URLs are for your own site serving private files: a fresh URL for every page view, made on your server with no request to Fileboy, and video playback. They can't be turned off one by one; rotating the private key stops them all.

Expiring links

How it worksMake onePublic files and Signed URLs onlyTurn one offWhat someone opening it getsLimitsExpiring links or signed URLs?

Getting Started

Uploads

Delivery

Video

Libraries

API Reference

Expiring links

How it works

Make one

Public files and Signed URLs only

Turn one off

What someone opening it gets

Limits

Expiring links or signed URLs?

Expiring links