Data Types


Upload supports the following authorization methods:

Authorization MethodMaximum Level of AccessWhen to use


Download public files via the URL.

Hosting public media assets for your website.

JWT Cookie

Download private files via the URL.

Hosting files for logged-in members of your site.

Public API Key

Download and upload files (per the API key's configuration).

Accepting file uploads on forms.

Public API Key + JWT Auth Header

All operations (per the JWT's configuration).

Allowing your site's users to delete specific files.

Secret API Key

All operations (per the API key's configuration).

Performing admin tasks via your backend services.

Upload Dashboard

All operations.

Performing admin tasks via our easy-to-use UI.

Public file access

Public file access refers to anonymous/unauthenticated downloads:

Publicly downloadable file

By default, all files are public.

To make files private, you must change the parent folder's permissions from "Public" to either "Private" or "Limited" access.

This makes files within the folder private:

Privately accessible file

Please note:

  1. Public permissions are configured on a per-folder basis.

  2. Public permissions can be configured via the Upload Dashboard (see example above) or using the PutFolder endpoint.

  3. Public permissions are recursive, meaning if you don't define public permissions for a folder, the parent folder's permissions are used.

  4. You can create an unlimited number of folders, each with their own unique public permissions.

  5. Public API keys can upload to private folders. See: Configuring API key permissions

  6. Public API keys can download from private folders (although this is often not a desired configuration). See: Configuring API key permissions

  7. To control uploads/downloads via your backend API, please use JWTs.

Private file access

To download private files, use one of these options:

Option 1) Use the Upload Dashboard

Upload Dashboard users have full access to all resources (including private files).

This is the easiest way to access private files, as no code is required.

Option 2) Use an API Key

API keys can be configured with varying levels of access in the Upload Dashboard.

To attach an API key to an Upload API or Upload CDN request:

  1. Add an Authorization header to your HTTP request.

  2. The value for the HTTP header must be one of:

    • Option 1) prefix "Bearer " to your API key to produce the Authorization header value.

    • Option 2) use HTTP basic authorization, specifying apikey as your username, and your API key as your password.

The Upload SDKs perform the above for you.

Your API key must have sufficient permissions to the file you're accessing, see: Configuring API key permissions

Option 3) Use a Public API Key + JWT Auth Header

JWTs allow you to generate access permissions for your users at runtime, using your backend API.

To use JWTs with public API keys:

  1. Add the public API key to the Authorization request header (follow steps above).

  2. Add the JWT to the Authorization-Token request header.

To generate a JWT, see: Generating JWTs

JWT cookies allow you to create authenticated browser sessions for your users, giving them download access to private files directly via the URL.

JWT cookies allow <img /> elements that reference private files to render correctly.

To use JWT cookies:

  1. Create an API endpoint to generate JWTs. (See: Generating JWTs)

  2. Add a JWT cookie to your browser session using the beginAuthSession method from the Upload JS SDK or the Upload Widget:

    // Call this function after your user signs in.
    function onSignIn() {
    // URL for your auth API endpoint.
    // (It must return a JWT as a text/plain response body.)
    const authUrl = "https://your-web-app/your-auth-url"
    // Headers required by your API endpoint (e.g. 'authorization' header).
    const authHeaders = () => Promise.resolve({
    authorization: "some auth token"
    // Wait for authentication to complete.
    await upload.beginAuthSession(
  3. Append ?auth=true to your file URLs.

    The Upload JS SDK and the Upload Widget include a helper method:

    // Example result: ""
    upload.url("/uploads/file.jpg", {auth: true});

Configuring JWT permissions

To configure the permissions your JWTs grant to your users, see Generating JWTs.

Configuring API key permissions

To configure the permissions an API key grants to a user:

  1. Navigate to:

  2. Find & edit your API key

  3. Click the "Permissions" tab

  4. Click the "Add Path Permission" button

  5. Add the paths /my_folder/* and/or /my_folder/*/**

    The /* path suffix matches all children of the folder.

    The /*/** path suffix matches all grandchildren of the folder, recursively.

    Since they match different levels within the folder, you may want to specify both patterns, or just one of them.

  6. Set the relevant permissions for your new path permission(s), e.g. "Uploads" and "Downloads"

  7. Click "Save Changes"

Update API key path permissions

The above configuration allows users to perform uploads and downloads to /my_folder (recursively) with this API key.

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: