Upload.js Docs

Install Upload.js by including the Upload.js script on your webpage or by installing it as a module, through a package manager like NPM or YARN:

To get started, instantiate Upload with some basic configuration:

To create an upload button, add the following code to your webpage:

To wire-up the upload button from the previous step, use createFileInputHandler:

Parameters for createFileInputHandler

Alternatively if you have the file object already, you can use uploadFile:

Parameters for uploadFile

Specifying a file tag is optional, but we recommend it:

To display file upload progress:

To cancel an upload that's been started:

To download your file, simply browse to its file URL (this can be constructed from the file ID):

When saving references to files in your database, we recommend saving the file ID rather than the full file URL: it's shorter, and the Upload REST API takes file IDs instead of URLs.

To get a file URL from a file ID, you can use the url helper method:

To transform a file, append the desired transformation's "slug" to the file URL:

To find the "slug" for the transformation you want to use, go to the Upload Dashboard and browse the available transformations, then take note of the desired transformation's "slug".

The response from the URL will be the transformed file.

Transformations are easy to define in the Upload Dashboard.

Transformation definitions have the following structure:

Once you know which transformation you want to use, append its "slug" to the file URL:

The returned file will be the transformed file.

For example, if your transformation is called 300x200 and you wanted to transform the file with ID AYU81093TgPQauaR, then use the following URL:

You can restrict access such that only authenticated users of your web app can perform uploads and/or downloads.

To do this, complete the following steps:

1. Create a private/public RSA key pair:

   ssh-keygen -t rsa -b 4096 -m PEM -f jwt_rs256.key -q -N ""openssl rsa -in jwt_rs256.key -pubout -outform PEM -out jwt_rs256.key.pubcat jwt_rs256.keycat jwt_rs256.key.pub
2. Add the public key to your Upload account via the Upload Dashboard.
3. Make sure your backend API has access to the private key.
4. Add a new endpoint to your backend API:

   • HTTP verb: GET

   • Path: anything

   • Response content-type: text/plain

   • Response body: an encoded JWT (e.g. eyJhbGci1NiJ9.e35gDeaAu...)

     • The JWT must be signed using the private key from step (1) with the RS256 algorithm.

     • The JWT payload must use this exact structure:

       {
         iat: number; // Token creation timestamp (epoch seconds).
         exp: number; // Token expiration timestamp (epoch seconds).
         sub: string; // Current user ID or username.
         access: {
           upload: boolean;      // Can the user upload files?
           download: boolean | { // Can the user download files?
             tags?: string[];    // Limit downloads to certain files.
           };
         };
       }

5. Call beginAuthSession on upload-js after the user signs-in to your web app:

   const { Upload } = require("upload-js")
   const upload = new Upload({apiKey: "<YOUR_KEY_HERE>" })
   
   ...
   
   // Call this on sign-in.
   function onSignIn() {
   
     // URL for your auth endpoint (from step 4 above).
     const authUrl = "https://your-web-app/your-auth-url"
   
     // Headers required by your API (e.g. 'authorization' header).
     const authHeaders = () => Promise.resolve({
       authorization: "some auth token"
     })
   
     // Wait for authentication to complete.
     await upload.beginAuthSession(
       authUrl,
       authHeaders
     )
   }

6. Enforce authenticated uploads and/or downloads via the Upload Dashboard:

   

Congratulations! Users must now sign-in to your website to upload and/or download files!