thelastapi
Get started free

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.

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:

  1. The URL contains a signature. The url field becomes a signed link containing temporary authentication parameters (?expires=...&signature=...).
  2. 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.
  3. Unsigned requests are rejected. Attempting to open the base path without the signature parameters returns a 404 error.
Text
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 -> 404

When 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:

Terminal
vibiz files upload contract.pdf --folder legal --private

To upload the file to your isolated development environment instead of production, add the --dev flag:

Terminal
vibiz files upload test-statement.pdf --folder tests --private --dev

Using the JavaScript SDK

In a backend server running Node 20+, Bun, or Deno, install the @vibiz/app package:

Terminal
npm install @vibiz/app

The 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:

TypeScript
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:

Terminal
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:

JSON
{
  "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"
}

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:

TypeScript
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:

Terminal
vibiz files get file_01k7xyz987 --json

Reading 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:

Terminal
curl https://thelastapi.dev/v1/projects/prj_123/files/file_01k7xyz987/content \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -o local-document.pdf

The CLI provides the download command to pull private bytes directly to your machine:

Terminal
vibiz files download file_01k7xyz987 -o ./local-document.pdf

Toggling 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:

Terminal
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:

FieldTypeDescription
privatebooleanSet true to require signed URLs; false for permanent public links
namestringRename the file
folderstring | nullMove to a folder, or null to clear the folder
tagsstring[]Array of up to 20 tag labels
notestring | nullDescriptive 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 (upload or ai).
  • since and until: Filter by ISO date strings or relative durations like 30m, 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:

Terminal
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:

Terminal
vibiz files rm file_01k7xyz987

Once 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_KEY created via vibiz dev) write and read files from the development environment.
  • Production keys write and read files from production.
  • The HTTP API routes accept ?env=development to explicitly specify the environment.
  • CLI commands accept the --dev flag 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