Private files with signed links
Upload private files or toggle existing files to private to get signed URLs that expire after one hour, protecting assets from unauthorized access.
On this page 10 sections
To create a private file with a signed link, upload it with the private flag enabled or update an existing file's properties to private. thelastapi generates a signed url that remains valid for exactly one hour, marked by an ISO timestamp in url_expires_at. Anyone attempting to visit the bare link without a valid signature receives a 404 error.
This guide explains how signed file URLs work in thelastapi, how to upload private files from your code, how to fetch fresh links when previous ones expire, and how file security works across development and production environments.
How signed links work in Files
Every project in thelastapi includes Files, a managed drive where files can be stored, organized, and retrieved. By default, files uploaded or generated by AI models receive permanent links at https://thelastapi.dev/f/<key>/<name>. The 32-character random key ensures that public links cannot be guessed or enumerated, which is ideal for assets like avatars, public social media attachments, or graphics discussed in our guide to where to keep AI-generated images, with permanent links.
Public permanent URLs are not appropriate for sensitive business documents such as invoices, contracts, payroll spreadsheets, or user data exports. Setting a file to private changes two access characteristics:
- The URL contains a signature. The
urlfield becomes a signed link containing temporary authentication parameters (?expires=...&signature=...). - Access expires after 60 minutes. The file object includes
url_expires_at, an ISO 8601 timestamp exactly one hour in the future. Once that hour passes, the link stops working. - Unsigned requests are rejected. Attempting to open the base path without the signature parameters returns a
404error.
Public URL: https://thelastapi.dev/f/Qm9x123.../statement.pdf
Private URL: https://thelastapi.dev/f/Qm9x123.../statement.pdf?expires=1793282400&signature=abc...
Bare access: https://thelastapi.dev/f/Qm9x123.../statement.pdf -> 404When an authorized user needs access again later, your application requests the file by ID. thelastapi immediately responds with a fresh signed link valid for another hour.
Uploading a private file with code
You can upload private files using the command line, the JavaScript SDK, or standard HTTP requests from any programming language.
Using the CLI
To upload a local document directly from your terminal and make it private, pass the --private flag to the vibiz files upload command:
vibiz files upload contract.pdf --folder legal --privateTo upload the file to your isolated development environment instead of production, add the --dev flag:
vibiz files upload test-statement.pdf --folder tests --private --devUsing the JavaScript SDK
In a backend server running Node 20+, Bun, or Deno, install the @vibiz/app package:
npm install @vibiz/appThe package uses your project's server key (VIBIZ_APP_KEY), which already provides access to files, the database, sign-in, and AI gateway tools through one key for your whole app. Set private: true in the upload options:
import { vibiz } from '@vibiz/app';
import fs from 'node:fs/promises';
const fileBuffer = await fs.readFile('./customer-invoice.pdf');
const file = await vibiz.files.upload(fileBuffer, {
name: 'customer-invoice.pdf',
contentType: 'application/pdf',
folder: 'invoices',
private: true,
});
console.log('Signed URL:', file.url);
console.log('Expires at:', file.url_expires_at);
console.log('File ID:', file.id);For more details on managing public uploads alongside private ones, see our tutorial on file uploads for your app, with permanent links.
Using the HTTP API
If you use Python, Go, or a shell script, make a POST request to /v1/app/files with private=1 in the query string:
curl -X POST "https://thelastapi.dev/v1/app/files?name=tax-return.pdf&folder=taxes&private=1" \
-H "Authorization: Bearer $VIBIZ_APP_KEY" \
-H "Content-Type: application/pdf" \
--data-binary "@tax-return.pdf"The API returns the complete file object:
{
"object": "file",
"id": "file_01k7xyz987",
"environment": "production",
"name": "tax-return.pdf",
"folder": "taxes",
"content_type": "application/pdf",
"kind": "other",
"size": 1048576,
"width": null,
"height": null,
"duration_seconds": null,
"source": "upload",
"ai": null,
"tags": [],
"note": null,
"private": true,
"url": "https://thelastapi.dev/f/Qm9x123.../tax-return.pdf?expires=1793282400&signature=abc...",
"url_expires_at": "2026-10-28T11:00:00.000Z",
"created_at": "2026-10-28T10:00:00.000Z",
"console_url": "https://thelastapi.dev/projects/prj_123/files?env=production&file=file_01k7xyz987"
}Refreshing expired links
Because signed URLs expire after one hour, never store the full expiring url in your persistent database columns. Instead, save the permanent file id (file_...).
When a client requests a download link, retrieve the file record by its ID using the HTTP endpoint GET /v1/app/files/:fileId. Each request returns a freshly signed URL with a new expiration timestamp:
export async function getInvoiceDownloadUrl(fileId: string) {
const response = await fetch(`https://thelastapi.dev/v1/app/files/${fileId}`, {
headers: {
Authorization: `Bearer ${process.env.VIBIZ_APP_KEY}`,
},
});
if (!response.ok) {
throw new Error('Failed to retrieve file record');
}
const file = await response.json();
return {
url: file.url,
expiresAt: file.url_expires_at,
};
}In the CLI, you can inspect the file and obtain a fresh signed URL at any time:
vibiz files get file_01k7xyz987 --jsonReading raw file bytes directly
When your backend processes file contents internally—such as analyzing a CSV file, extracting metadata from a PDF, or proxying bytes through a custom stream—you do not need a signed URL.
Retrieve raw binary data directly using the content route with an authenticated server key:
curl https://thelastapi.dev/v1/projects/prj_123/files/file_01k7xyz987/content \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-o local-document.pdfThe CLI provides the download command to pull private bytes directly to your machine:
vibiz files download file_01k7xyz987 -o ./local-document.pdfToggling privacy on existing files
You can switch files between public and private states at any point. For example, if a document was uploaded publicly by mistake, you can restrict it immediately without re-uploading the underlying data.
Send a PATCH request to /v1/projects/:id/files/:fileId:
curl -X PATCH https://thelastapi.dev/v1/projects/prj_123/files/file_01k7xyz987 \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"private": true}'The PATCH route accepts several optional parameters:
| Field | Type | Description |
|---|---|---|
private | boolean | Set true to require signed URLs; false for permanent public links |
name | string | Rename the file |
folder | string | null | Move to a folder, or null to clear the folder |
tags | string[] | Array of up to 20 tag labels |
note | string | null | Descriptive text notes |
When private is set to true, existing permanent links stop resolving immediately. Setting private to false restores the unauthenticated permanent URL.
Listing, filtering, and deleting files
To view your files, list them using GET /v1/projects/:id/files (or GET /v1/app/files). The endpoint accepts filtering parameters:
type: Filter by kind (image,video,audio,other).source: Filter by source (uploadorai).sinceanduntil: Filter by ISO date strings or relative durations like30m,4h,2d,1w.q: Search terms across file names, prompts, tags, and notes.folder: Filter by folder path.
In the CLI, search or list files with:
vibiz files --since 2d --source upload
vibiz files search "contract"To delete a file permanently, call DELETE /v1/projects/:id/files/:fileId or use the CLI command:
vibiz files rm file_01k7xyz987Once deleted, the raw bytes are erased immediately and all signed links stop working.
Supported file types, headers, and limits
Files supports individual uploads up to 50 MB each.
- Document and archive formats: PDF, text, CSV, Markdown, JSON, ZIP, and general binary files.
- Image formats: PNG, JPEG, GIF, WebP, AVIF, HEIC, and SVG.
- Video formats: MP4, WebM, and QuickTime.
- Audio formats: MP3, WAV, OGG, WebM, AAC, FLAC, and M4A.
Files are served with their detected MIME type, X-Content-Type-Options: nosniff, an ETag, and Accept-Ranges: bytes so clients can seek within audio and video files. Headers handle delivery securely:
- Inline delivery: Images, videos, audio, and PDF files serve with
Content-Disposition: inline. - Attachment delivery: General binary files, text, and SVG files are served sandboxed with
Content-Disposition: attachment.
To prevent uploaded assets from executing as dynamic application pages, HTML, JavaScript, and XML uploads are refused with a 400 invalid_request error on param: "content-type".
Environments and key access
Every project maintains two distinct environments: production and development. Files are strictly partitioned between them:
- Development keys (
VIBIZ_APP_KEYcreated viavibiz dev) write and read files from the development environment. - Production keys write and read files from production.
- The HTTP API routes accept
?env=developmentto explicitly specify the environment. - CLI commands accept the
--devflag to target development.
As detailed in Keys and environments, files represent application content rather than system secrets. Both Full-access keys and Limited keys can read, upload, and delete files in either environment. Storage is free during the beta period. Bytes stored by your project are tracked daily under files.storage in your billing usage and can be inspected via vibiz usage --by tool.
Next steps
To integrate private storage into your backend routes, consult the complete API reference on the Files documentation page. If you are building a new application from scratch, read what is thelastapi to provision your hosting, database, and storage with a single key.
Frequently asked questions
How long is a signed link valid for private files?
A signed URL is valid for exactly one hour. The exact expiration timestamp is returned in the `url_expires_at` property of the file object.
What happens when someone opens a private file URL without a signature or after expiration?
The request returns a `404` error. Unsigned links or links with expired signatures cannot view or download the file.
Can I change an existing public file to a private file without re-uploading?
Yes, send a PATCH request to `/v1/projects/:id/files/:fileId` with `{"private": true}`. The change takes effect immediately, turning off the permanent link and issuing signed URLs for future reads.
How do I refresh an expired signed URL for my users?
Make a GET request to `/v1/app/files/:fileId` with your app key or run `vibiz files get <id>` in the CLI. The API returns a fresh signed `url` along with an updated `url_expires_at` timestamp.
What is the file size limit for private uploads?
You can upload files up to 50 MB each across supported types, including PDFs