Data Types

Upload Widget: Methods

These methods are declared on the uploader object (the object returned by the Uploader(...) function):

open

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 });

url

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"

beginAuthSession

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"
})
);

endAuthSession

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();

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: