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 Bytescale 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:

Bytescale 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 Bytescale Dashboard.

To attach an API key to a Bytescale API or Bytescale 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 Bytescale 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 access to private files directly via the URL.

To use JWT cookies:

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

2. Call the AuthManager.beginAuthSession method from the Bytescale JavaScript SDK to start a JWT session.

   Calling AuthManager.beginAuthSession on the Bytescale JavaScript SDK will also cause uploads from the Bytescale Upload Widget to be authenticated using JWTs.

   import * as Bytescale from "@bytescale/sdk";
   
   // Call this function after your user signs in:
   async function onSignIn() {
   
     // The URL for your auth API endpoint.
     // Your URL must:
     // - Return a JWT as plain text.
     // - Return a 'content-type: text/plain' response header.
     // - Return a 200 status code.
     // - Return a signed JWT (i.e. the JWT must include 2x "." characters) using RS256.
     // - The public key certificate must be added to the Bytescale Dashboard.
     // - The JWT must not be wrapped with "".
     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 Bytescale.AuthManager.beginAuthSession({
       accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
       authUrl,
       authHeaders
     });
   }

3. File uploads from the Bytescale Upload Widget and Bytescale JavaScript SDK will now be authenticated using JWTs, as will all other requests from the Bytescale JavaScript SDK.

4. File downloads will require ?auth=true appending to the file URL (this applies to privately-accessible files only).

   The Bytescale JavaScript SDK includes a UrlBuilder that does this for you:

   Downloading a private image (raw):

   import * as Bytescale from "@bytescale/sdk";
   
   // Returns: "https://upcdn.io/1234abc/raw/example.jpg?auth=true"
   Bytescale.UrlBuilder.url({
     accountId: "1234abc",
     filePath: "/example.jpg",
     options: {
       auth: true
     }
   });

   Downloading a private image (transformed):

   import * as Bytescale from "@bytescale/sdk";
   
   // Returns: "https://upcdn.io/1234abc/image/example.jpg?w=800&h=600&auth=true"
   Bytescale.UrlBuilder.url({
     accountId: "1234abc",
     filePath: "/example.jpg",
     options: {
       transformation: "image",
       transformationParams: {
         w: 800,
         h: 600
       },
       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://www.bytescale.com/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"