Authorization

Public file access refers to anonymous/unauthenticated downloads:

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:

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.

To download private files, use one of these options:

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.

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

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.

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(
       authUrl,
       authHeaders
     )
   }

3. Append ?auth=true to your file URLs.

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

   // Example result: "https://upcdn.io/AYU8109/raw/uploads/file.jpg?auth=true"
   upload.url("/uploads/file.jpg", {auth: true});

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

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

1. Navigate to: https://upload.io/dashboard/security/api_keys

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"