Private Storage

Next.js (/app)

Choose a framework to optimize documentation to:

Private Storage

Vercel Blob is available on all plans

Those with the owner, member, developer role can access this feature

Private storage requires a private Blob store and is available starting with:

@vercel/blob TypeScript SDK >= 2.3
vercel Python SDK >= 0.5.0
vc Vercel CLI >= 50.20.0

Private Blob stores require authentication for all read and write operations, ensuring files are only accessible to authenticated requests. Use private storage for sensitive documents, user content, and applications with custom authentication.

See differences with public storage.

Creating a private Blob store

You can create a private Blob store from the Vercel dashboard or the CLI:

Dashboard:
1. Go to your project's Storage tab
2. Select Create Database, then choose Blob
3. Select Continue, then set the access to Private
CLI: Run vercel blob create-store [name] --access private

When your code runs on Vercel, the SDK authenticates using OIDC by default. Connect your store to a project so Vercel adds the OIDC token and BLOB_STORE_ID to your environment automatically. For team-level stores or code that runs outside Vercel, see Authentication.

Uploading files

Upload files to a private Blob store using put() with access: 'private':

app/api/upload/route.ts

import { put } from '@vercel/blob';
 
export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get('file') as File;
 
  const blob = await put(file.name, file, {
    access: 'private',
  });
 
  return Response.json(blob);
}

See the server uploads and client uploads guides for detailed instructions on uploading files.

Delivering private blobs

Every file uploaded to a private Blob store gets a URL in the form of https://<store-id>.private.blob.vercel-storage.com/<pathname>. This URL is not publicly accessible. Fetch its content with the get() SDK method. The SDK supports OpenID Connect (OIDC) and BLOB_READ_WRITE_TOKEN authentication. When your code runs on Vercel, it defaults to OIDC, which is preferred because its short-lived tokens rotate automatically. See accessing without the SDK.

To serve private blobs to your users, create a route that authenticates the request, fetches the blob using get(), and streams the response. For example, a route like https://example.com/api/file?pathname=documents/report.pdf:

app/api/file/route.ts

import { type NextRequest, NextResponse } from 'next/server';
import { get } from '@vercel/blob';
 
export async function GET(request: NextRequest) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.nextUrl.searchParams.get('pathname');
 
  if (!pathname) {
    return NextResponse.json({ error: 'Missing pathname' }, { status: 400 });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return new NextResponse('Not found', { status: 404 });
  }
 
  return new NextResponse(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
    },
  });
}

app/api/file/route.ts

import { type NextRequest, NextResponse } from 'next/server';
import { get } from '@vercel/blob';
 
export async function GET(request: NextRequest) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.nextUrl.searchParams.get('pathname');
 
  if (!pathname) {
    return NextResponse.json({ error: 'Missing pathname' }, { status: 400 });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return new NextResponse('Not found', { status: 404 });
  }
 
  return new NextResponse(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
    },
  });
}

app/api/file/route.js

import { NextResponse } from 'next/server';
import { get } from '@vercel/blob';
 
export async function GET(request) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.nextUrl.searchParams.get('pathname');
 
  if (!pathname) {
    return NextResponse.json({ error: 'Missing pathname' }, { status: 400 });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return new NextResponse('Not found', { status: 404 });
  }
 
  return new NextResponse(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
    },
  });
}

pages/api/file.ts

import type { NextApiRequest, NextApiResponse } from 'next';
import { Readable } from 'node:stream';
import { get } from '@vercel/blob';
 
export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.query.pathname as string;
 
  if (!pathname) {
    return response.status(400).json({ error: 'Missing pathname' });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return response.status(404).send('Not found');
  }
 
  response.setHeader('Content-Type', result.blob.contentType);
  response.setHeader('X-Content-Type-Options', 'nosniff');
  Readable.fromWeb(result.stream).pipe(response);
}

pages/api/file.js

import { Readable } from 'node:stream';
import { get } from '@vercel/blob';
 
export default async function handler(request, response) {
  // Your auth goes here: await authRequest(request)
 
  const { pathname } = request.query;
 
  if (!pathname) {
    return response.status(400).json({ error: 'Missing pathname' });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return response.status(404).send('Not found');
  }
 
  response.setHeader('Content-Type', result.blob.contentType);
  response.setHeader('X-Content-Type-Options', 'nosniff');
  Readable.fromWeb(result.stream).pipe(response);
}

api/file.ts

import { get } from '@vercel/blob';
 
export default async function handler(request: Request) {
  // Your auth goes here: await authRequest(request)
 
  const { searchParams } = new URL(request.url);
  const pathname = searchParams.get('pathname');
 
  if (!pathname) {
    return new Response(JSON.stringify({ error: 'Missing pathname' }), {
      status: 400,
    });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return new Response('Not found', { status: 404 });
  }
 
  return new Response(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
    },
  });
}

api/file.js

import { get } from '@vercel/blob';
 
export default async function handler(request) {
  // Your auth goes here: await authRequest(request)
 
  const { searchParams } = new URL(request.url);
  const pathname = searchParams.get('pathname');
 
  if (!pathname) {
    return new Response(JSON.stringify({ error: 'Missing pathname' }), {
      status: 400,
    });
  }
 
  const result = await get(pathname, { access: 'private' });
 
  if (result?.statusCode !== 200) {
    return new Response('Not found', { status: 404 });
  }
 
  return new Response(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
    },
  });
}

See the get() API reference for full option details and return values.

Accessing without the SDK

To access a private blob directly from code running on Vercel, pass the short-lived VERCEL_OIDC_TOKEN in the Authorization header. OIDC is preferred over the long-lived BLOB_READ_WRITE_TOKEN because it rotates automatically:

Terminal

curl https://my-store-id.private.blob.vercel-storage.com/my-file.png \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

When you use the token directly like this, you handle expiry yourself: requests fail with a 403 error once the token expires. The SDK refreshes the token automatically, so prefer it when possible.

When code runs outside Vercel or you need a static credential, pass BLOB_READ_WRITE_TOKEN instead:

Terminal

curl https://my-store-id.private.blob.vercel-storage.com/my-file.png \
  -H "Authorization: Bearer $BLOB_READ_WRITE_TOKEN"

Caching

Private blobs have two layers of caching:

CDN cache (between your Function and the blob store): When your Function fetches a private blob, the request goes through Vercel's CDN cache. If the blob is already cached, no Fast Origin Transfer is charged. You control the CDN cache duration with the cacheControlMaxAge option when uploading (defaults to 1 month), the same way as public blobs.
Browser cache (between the browser and your Function): You control this through the Cache-Control header on your Function's response.

If you don't set a Cache-Control header, Vercel sends Cache-Control: public, max-age=0, must-revalidate by default. The browser keeps the response on disk but always revalidates with your server before using it, so your auth logic runs on every request and the user always gets the correct content.

Since you're serving private blobs, we recommend setting Cache-Control: private, no-cache. This restricts caching to the browser only while still allowing efficient 304 responses:

const result = await get(pathname, { access: 'private' });
 
return new NextResponse(result.stream, {
  headers: {
    'Content-Type': result.blob.contentType,
    'X-Content-Type-Options': 'nosniff',
    'Cache-Control': 'private, no-cache',
  },
});

For sensitive data (tokens, banking, PII), use Cache-Control: private, no-store instead. Nothing is stored on disk and every request is a full fetch.

Consistent reads

Reads are served through Vercel's CDN cache by default. When you overwrite a blob at the same pathname, the changes may take up to 60 seconds to propagate through our cache. During that window, get() can return the previous version. When a read must reflect the latest write, such as fetching a file right after updating it, pass useCache: false:

const result = await get(pathname, { access: 'private', useCache: false });

This serves the read directly from origin storage and guarantees the latest content. These reads are slower and incur Fast Origin Transfer on each request. Keep the default for content that doesn't change after upload, such as blobs uploaded with unique pathnames or with addRandomSuffix: true.

Presigned GET URLs accept the same useCache option in presignUrl().

Browser caching with conditional requests

When you set Cache-Control: private, no-cache, the browser caches the response but revalidates on every request by sending an If-None-Match header with the ETag it received previously. You can forward this header to the blob store to get a 304 Not Modified response when the blob hasn't changed, avoiding re-downloading the full file:

app/api/file/route.ts

import { type NextRequest, NextResponse } from 'next/server';
import { get } from '@vercel/blob';
 
export async function GET(request: NextRequest) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.nextUrl.searchParams.get('pathname');
  if (!pathname) {
    return NextResponse.json({ error: 'Missing pathname' }, { status: 400 });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: request.headers.get('if-none-match') ?? undefined,
  });
 
  if (!result) {
    return new NextResponse('Not found', { status: 404 });
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    return new NextResponse(null, {
      status: 304,
      headers: {
        ETag: result.blob.etag,
        'Cache-Control': 'private, no-cache',
      },
    });
  }
 
  return new NextResponse(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
      ETag: result.blob.etag,
      'Cache-Control': 'private, no-cache',
    },
  });
}

app/api/file/route.ts

import { type NextRequest, NextResponse } from 'next/server';
import { get } from '@vercel/blob';
 
export async function GET(request: NextRequest) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.nextUrl.searchParams.get('pathname');
  if (!pathname) {
    return NextResponse.json({ error: 'Missing pathname' }, { status: 400 });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: request.headers.get('if-none-match') ?? undefined,
  });
 
  if (!result) {
    return new NextResponse('Not found', { status: 404 });
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    return new NextResponse(null, {
      status: 304,
      headers: {
        ETag: result.blob.etag,
        'Cache-Control': 'private, no-cache',
      },
    });
  }
 
  return new NextResponse(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
      ETag: result.blob.etag,
      'Cache-Control': 'private, no-cache',
    },
  });
}

app/api/file/route.js

import { NextResponse } from 'next/server';
import { get } from '@vercel/blob';
 
export async function GET(request) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.nextUrl.searchParams.get('pathname');
  if (!pathname) {
    return NextResponse.json({ error: 'Missing pathname' }, { status: 400 });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: request.headers.get('if-none-match') ?? undefined,
  });
 
  if (!result) {
    return new NextResponse('Not found', { status: 404 });
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    return new NextResponse(null, {
      status: 304,
      headers: {
        ETag: result.blob.etag,
        'Cache-Control': 'private, no-cache',
      },
    });
  }
 
  return new NextResponse(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
      ETag: result.blob.etag,
      'Cache-Control': 'private, no-cache',
    },
  });
}

pages/api/file.ts

import type { NextApiRequest, NextApiResponse } from 'next';
import { Readable } from 'node:stream';
import { get } from '@vercel/blob';
 
export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse,
) {
  // Your auth goes here: await authRequest(request)
 
  const pathname = request.query.pathname as string;
  if (!pathname) {
    return response.status(400).json({ error: 'Missing pathname' });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: (request.headers['if-none-match'] as string) ?? undefined,
  });
 
  if (!result) {
    return response.status(404).send('Not found');
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    response.setHeader('ETag', result.blob.etag);
    response.setHeader('Cache-Control', 'private, no-cache');
    return response.status(304).end();
  }
 
  response.setHeader('Content-Type', result.blob.contentType);
  response.setHeader('X-Content-Type-Options', 'nosniff');
  response.setHeader('ETag', result.blob.etag);
  response.setHeader('Cache-Control', 'private, no-cache');
  Readable.fromWeb(result.stream).pipe(response);
}

pages/api/file.js

import { Readable } from 'node:stream';
import { get } from '@vercel/blob';
 
export default async function handler(request, response) {
  // Your auth goes here: await authRequest(request)
 
  const { pathname } = request.query;
  if (!pathname) {
    return response.status(400).json({ error: 'Missing pathname' });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: request.headers['if-none-match'] ?? undefined,
  });
 
  if (!result) {
    return response.status(404).send('Not found');
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    response.setHeader('ETag', result.blob.etag);
    response.setHeader('Cache-Control', 'private, no-cache');
    return response.status(304).end();
  }
 
  response.setHeader('Content-Type', result.blob.contentType);
  response.setHeader('X-Content-Type-Options', 'nosniff');
  response.setHeader('ETag', result.blob.etag);
  response.setHeader('Cache-Control', 'private, no-cache');
  Readable.fromWeb(result.stream).pipe(response);
}

api/file.ts

import { get } from '@vercel/blob';
 
export default async function handler(request: Request) {
  // Your auth goes here: await authRequest(request)
 
  const { searchParams } = new URL(request.url);
  const pathname = searchParams.get('pathname');
  if (!pathname) {
    return new Response(JSON.stringify({ error: 'Missing pathname' }), {
      status: 400,
    });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: request.headers.get('if-none-match') ?? undefined,
  });
 
  if (!result) {
    return new Response('Not found', { status: 404 });
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    return new Response(null, {
      status: 304,
      headers: {
        ETag: result.blob.etag,
        'Cache-Control': 'private, no-cache',
      },
    });
  }
 
  return new Response(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
      ETag: result.blob.etag,
      'Cache-Control': 'private, no-cache',
    },
  });
}

api/file.js

import { get } from '@vercel/blob';
 
export default async function handler(request) {
  // Your auth goes here: await authRequest(request)
 
  const { searchParams } = new URL(request.url);
  const pathname = searchParams.get('pathname');
  if (!pathname) {
    return new Response(JSON.stringify({ error: 'Missing pathname' }), {
      status: 400,
    });
  }
 
  const result = await get(pathname, {
    access: 'private',
    ifNoneMatch: request.headers.get('if-none-match') ?? undefined,
  });
 
  if (!result) {
    return new Response('Not found', { status: 404 });
  }
 
  // Blob hasn't changed — tell the browser to use its cached copy
  if (result.statusCode === 304) {
    return new Response(null, {
      status: 304,
      headers: {
        ETag: result.blob.etag,
        'Cache-Control': 'private, no-cache',
      },
    });
  }
 
  return new Response(result.stream, {
    headers: {
      'Content-Type': result.blob.contentType,
      'X-Content-Type-Options': 'nosniff',
      ETag: result.blob.etag,
      'Cache-Control': 'private, no-cache',
    },
  });
}

How it works:

First request: get() returns statusCode: 200 with stream and an ETag. The browser caches the response.
Subsequent requests: The browser sends If-None-Match with the cached ETag. When forwarded to the blob store, get() returns statusCode: 304 with stream: null — no data is re-downloaded.

Avoid caching private blob responses in Vercel's CDN cache (e.g. with s-maxage) and avoid relying on middleware for auth. While both can work, a middleware bug or misconfiguration could expose cached private content to the wrong users.

Instead, always verify auth directly in your route handler, right next to the get() call.

See Cache-Control headers for more details.

Learn more about Vercel's CDN cache.

Custom domains

Since private blobs are delivered through your own Functions, you can serve them from any custom domain. A common pattern is to create a dedicated Vercel project (e.g. "assets") for blob delivery:

Create a new Vercel project with a route handler that serves private blobs (as shown in delivering private blobs)
Connect your private Blob store to this project
Assign a custom domain to the project (e.g. content.mywebsite.com)

Requests to content.mywebsite.com/api/file?pathname=documents/report.pdf will then go through your auth logic and stream the blob to the user.

SEO and search engine indexing

Private blobs cannot be indexed by search engines since all read access requires authentication.

Download charges

When serving private blobs through Functions, you pay for:

Function fetches the blob from the store: Blob Data Transfer + Fast Origin Transfer on cache miss
Function responds to the browser: Fast Data Transfer + Fast Origin Transfer

Recommendations:

Private Blob stores are ideal for smaller sensitive files or when you need precise auth control
We do not recommend serving files larger than 100 MB through private Blob stores unless traffic is low
For large public media, use public storage which benefits from BDT rates (3x cheaper than FDT)

See pricing documentation for full details.

Upload charges

Upload charges depend on your implementation method:

Client Uploads: No data transfer charges for uploads
Server Uploads: Fast Data Transfer charges apply when your Vercel application receives the file

See pricing documentation for full details.

Last updated August 26, 2026

Cross-link map: Private Storage (/docs/vercel-blob/private-storage)

From the Vercel docs graph (built 2026-09-08T06:41:25.979Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Public Storage — Learn how to use public Vercel Blob storage to serve files accessible to anyone with the URL
The Complete Guide to Vercel Blob — Vercel Blob stores and serves files of any size through Vercel's global network. Learn how Blob works, what it costs, an
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.
How to upload and store files with Vercel — Vercel file uploads done right cover Server Actions, client-direct upload, and multipart for 5 TB files, with auth and c
Vercel Blob examples — Examples on how to use Vercel Blob in your applications

This page links to (16)

Cache-Control headers — Learn about the cache-control headers sent to each Vercel deployment and how to use them to control the caching behavior
Vercel CDN Cache — Learn how Vercel's CDN cache stores your content across a global network to reduce latency and origin load.
Vercel CDN overview — Vercel's CDN is a globally distributed platform that handles routing, caching, security, and compression for every deplo
Vercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the command
vercel blob — Learn how to interact with Vercel Blob storage using the vercel blob CLI command.
Working with domains — Learn how domains work and the options Vercel provides for managing them.
Vercel Functions — Build API routes, webhooks, and agent request handlers with Vercel Functions, then test and debug them with Vercel CLI.
CDN pricing and usage — Understand CDN pricing resources, monitor usage from your dashboard, and optimize Fast Data Transfer, Fast Origin Transf
Vercel Storage overview — Store files with Vercel Blob, runtime configuration with Global Config, and application data with Marketplace databases.
Vercel Blob — Vercel Blob is a scalable, cost-effective object storage service with private and public access modes for files up to 5
Client Uploads with Vercel Blob — Learn how to upload files larger than 4.5 MB directly from the browser to Vercel Blob
Public Storage — Learn how to use public Vercel Blob storage to serve files accessible to anyone with the URL
Server Uploads with Vercel Blob — Learn how to upload files to Vercel Blob using Server Actions and Route Handlers
Vercel Blob Pricing — Learn about the pricing for Vercel Blob.
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.
Vercel Signed URLs — Grant time-limited access to Vercel Blob URLs with signed tokens, and authorize browser-to-blob presigned uploads.

Pages that link here (9)

By site: vercel-changelog (2) · vercel-kb (1) · vercel-docs (6)

From vercel-changelog

From vercel-kb

Vercel Blob vs Netlify Blobs — Compare Vercel Blob and Netlify Blobs on storage model, public URLs, delivery, limits, and pricing to choose the right o

From vercel-docs

vercel blob — Learn how to interact with Vercel Blob storage using the vercel blob CLI command.
Vercel Documentation Sitemap — Browse Vercel documentation pages with summaries, prerequisites, and topics.
Vercel Blob — Vercel Blob is a scalable, cost-effective object storage service with private and public access modes for files up to 5
Security — Learn how your Vercel Blob store is secured
Vercel Blob Pricing — Learn about the pricing for Vercel Blob.
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.

Blob

Public Storage

Was this helpful?

Build with AI

Deploy & scale

Operate & protect

Resources

Private Storage

Creating a private Blob store

Uploading files

Delivering private blobs

Accessing without the SDK

Caching

Consistent reads

Browser caching with conditional requests

Custom domains

SEO and search engine indexing

Download charges

Upload charges

Cross-link map: Private Storage (/docs/vercel-blob/private-storage)

Semantically closest pages

This page links to (16)

Pages that link here (9)

From vercel-changelog

From vercel-kb

From vercel-docs

Cross-link map: Private Storage (/docs/vercel-blob/private-storage)

Semantically closest pages

This page links to (16)

Pages that link here (9)

From vercel-changelog

From vercel-kb

From vercel-docs