Presigned URLs

There are situations where you may need to upload a file client side instead of server side, but doing so might risk exposing an API key. To solve this you can create a presigned upload URL on the server and then pass it to the client for it to be consumed. Creating signed upload URLs can be done with either the Files SDK or the API, and you can designate how long the URL is valid for, how large the file can be, the type of file allowed, or extra metadata like a name and keyvalues.

For a more robust example, check out our guides on Hono and React!

​

Usage

Setting up a server side API endpoint might look something like this:

import { type NextRequest, NextResponse } from "next/server";
import { pinata } from "@/utils/config"; // Import the Pinata SDK instance

export const dynamic = "force-dynamic";

export async function GET() {
  // Handle your auth here to protect the endpoint
  try {
    const url = await pinata.upload.public.createSignedURL({
      expires: 30, // The only required param
      mimeTypes: ["text/*"], // Optional restriction for certain file types
      maxFileSize: 5000000 // Optional file size limit
    })
    return NextResponse.json({ url: url }, { status: 200 }); // Returns the signed upload URL
  } catch (error) {
    console.log(error);
    return NextResponse.json({ text: "Error creating signed URL:" }, { status: 500 });
  }
}

Then back on the client side code, you can upload using the signed URL instead of the regular upload endpoint.

const urlRequest = await fetch("/api/url"); // Fetches the temporary upload URL from your server
const urlResponse = await urlRequest.json(); // Parse response
const upload = await pinata.upload.public
  .file(file)
  .url(urlResponse.url); // Upload the file with the signed URL

​

Reference

Below are the availble parameters for presigned URLs

​

expires

• Type: number

The number of seconds the signed URL should be valid for

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
});

​

name (Optional)

• Type: string

Name for the file to be uploaded

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	name: "My Cool File"
});

​

mimeTypes (Optional)

• Type: string[]

Specify allowed file mime types and prevent uploads from files that do not match. Accepts wildcard mime types as well.

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	mimeTypes: [
	  "image/*",
		"application/json"
	]
});

​

maxFileSize (Optional)

• Type: number

Restrict upload to a specified file size in bytes

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	maxFileSize: 50000 // 50kb
});

​

groupId (Optional)

• Type: string

The target groupId the file would be uploaded to

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	groupId: "ad4bc3bf-8794-49e7-94ff-fea1ce745779"
});

​

keyvalues (Optional)

• Type: Record<string, string>

Keyvalue pairs for the uploaded file

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	keyvalues: {
	  env: "prod"
	}
});

​

date (Optional)

• Type: number

A UNIX timestamp of the date a URL is signed

const date = Math.floor(new Date().getTime() / 1000);
//date: 1724943711

const url = await pinata.upload.public.createSignedURL({
	expires: 30,
	date: date
});