Upload Widget: Methods

Displays the widget and waits for the user to select their file(s), and then returns the result.

Signature

function open(configuration?: UploadWidgetConfig): Promise<Array<UploadWidgetResult>>

Parameters

See: Configuration

Result promise

See: Result

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.
uploader.open({ maxFileCount: 1 });

Gets the URL for an uploaded file (takes a filePath and returns a URL).

We recommend saving filePath values instead of fileUrl values to your database, as this allows you to change other parts of the URL in future (such as the URL's domain name — if you upgrade to a custom domain — or the "file transformation" part of the URL).

Signature

function url(filePath: string, urlParams?: { auth?: boolean; transformation?: string; }): string

Result

"https://upcdn.io/abc1234/thumbnail/uploads/example.jpg"

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.
const fileUrl  = uploader.url("/uploads/example.jpg", { transformation: "thumbnail" });
//    fileUrl  = "https://upcdn.io/abc1234/thumbnail/uploads/example.jpg"

Call this method in your client-side code after the user has signed in.

This allows the user to:

• Upload private files based on the permissions inside the UploadJwt (issued by your backend API).

• Download private files based on the permissions inside the UploadJwt (issued by your backend API).

  • The beginAuthSession method starts a cookie-based auth session with the Upload CDN to allow private file downloads via the URL, without needing to pre-sign URLs. For example, if your webpage contains <img> elements that reference private images, you can use beginAuthSession to allow these images to render in the current browser tab.

    You must add ?auth=true to your file URLs when using cookie-based auth.

  • Alternatively, you can download private files by passing your JWT via the Authorization-Token request header, and your public API key via the Authorization request header (see authorization for more information).

The authUrl is a simple GET endpoint you need to implement to return an UploadJwt.

See: Authorization

Signature

function beginAuthSession(authUrl: string, authHeaders: () => Promise<Record<string, string>>): Promise<void>

Prerequisites

Implement a backend API endpoint that generates a public/private key JWT, with its payload structured as an UploadJwt, and its public key certificate added to your JWT Certificates.

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.
uploader.beginAuthSession(
  "https://your-api-domain.example.com/auth",
  async () => ({
    Authorization: "SomeAuthorizationHeaderRequiredByYourApi"
  })
);

Ends an authorized browser session, preventing the user from downloading further private files.

Signature

function endAuthSession(): Promise<void>

Prerequisites

Can only be called after a successful call to beginAuthSession.

Example

const uploader = Uploader({ apiKey: "free" }); // Replace "free" with your API key.

// User signs in:
uploader.beginAuthSession(
  "https://your-api-domain.example.com/auth",
  async () => ({
    Authorization: "SomeAuthorizationHeaderRequiredByYourApi"
  })
);

// User downloads files:
// ...

// User signs out:
uploader.endAuthSession();