# 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.

**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](https://thelastapi.dev/docs/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](https://thelastapi.dev/blog/store-ai-generated-images-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.

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

```bash
vibiz files upload contract.pdf --folder legal --private
```

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

```bash
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](https://thelastapi.dev/docs/app-sdk) package:

```bash
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](https://thelastapi.dev/blog/one-key-whole-app-stack). Set `private: true` in the upload options:

```ts
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](https://thelastapi.dev/blog/file-uploads-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:

```bash
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"
}
```

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

```ts
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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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 (`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:

```bash
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:

```bash
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](https://thelastapi.dev/docs/keys), 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](https://thelastapi.dev/docs/files). If you are building a new application from scratch, read [what is thelastapi](https://thelastapi.dev/docs/introduction) 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

---

Published 2026-11-15 · https://thelastapi.dev/blog/private-files-signed-links
