Skip to navigation
UploadingFile Uploader

File Uploader security settings

Signed uploads

Signed uploads control who can upload files to your project. Your backend issues a credential, the uploader sends it with every Upload API request, and Uploadcare rejects anything without one.

Set authToken to a function that fetches a token from your backend. This needs File Uploader 1.35.1 or later. Versions that predate the option ignore it without a warning and the upload goes out unsigned.

const config = document.querySelector('uc-config');
config.authToken = async () => {
  const response = await fetch('/uploadcare-token');
  // `fetch` doesn't throw on a 500, and a body without a token gives
  // `undefined`. Check both, so a failure says what actually went wrong.
  if (!response.ok) throw new Error(`token endpoint: ${response.status}`);
  const { token } = await response.json();
  if (!token) throw new Error('token endpoint returned no token');
  return token;
};

The uploader caches the token and replaces it 30 seconds before it expires, so this runs once rather than once per request. When Uploadcare refuses a token as expired or spent, the uploader drops it, asks your function for another and retries that upload once. See signed uploads for enabling the feature, issuing tokens, and limiting one to particular endpoints or a number of operations. If you use the AI Image Editor plugin, it sends the same token. Generation has its own setting, Signed AI image generation, which is on by default, so the plugin needs authToken even when uploads are unsigned.

If your function throws, the file fails to upload with an AUTH_TOKEN_ERROR, separate from the errors Uploadcare itself reports: it means your token endpoint is unreachable or the user’s session is gone. The thrown failure is on payload.error.cause. See handling a failing token function.

When Uploadcare refuses the token, the file fails with an UPLOAD_ERROR instead, and the server’s code (ScopeForbiddenError, OperationsLimitExceededError and so on) is on payload.error.code:

const ctx = document.querySelector('uc-upload-ctx-provider');
ctx.addEventListener('file-upload-failed', (e) => {
  for (const { type, payload } of e.detail.errors) {
    if (type === 'AUTH_TOKEN_ERROR') {
      console.warn('token endpoint failed', payload.error.cause);
    } else if (payload?.error?.code) {
      // Uploadcare refused the request. An expired or spent token has already
      // been retried once with a fresh one, so reaching here means the second
      // token was refused too.
      console.warn('upload refused', payload.error.code);
    }
  }
});

Projects still on the legacy signature and expire parameters set secureSignature and secureExpire directly, or use secureUploadsSignatureResolver to fetch a fresh signature before the old one expires. See signed uploads with a signature for generating one, and moving from signatures for moving over.

Secure delivery proxy

There are two ways to point File Uploader to a signing proxy:

  1. Using the secureDeliveryProxy option:

The secureDeliveryProxy parameter can be used with signed URLs. It defines a URL template for your signing proxy.

Value for secureDeliveryProxy is a string template with the following variables:

  • previewUrl

That means that you can use {{previewUrl}} in your template to insert the URL of a file to proxify.

<uc-config
  secure-delivery-proxy="https://domain.com/preview?url={{previewUrl}}"
></uc-config>
  1. Using the secureDeliveryProxyUrlResolver option:
const config = document.querySelector('uc-config');
config.secureDeliveryProxyUrlResolver = async (previewUrl, { uuid, cdnUrlModifiers, fileName }) => {
  const yourAuthToken = await fetch('https://your-backend.com/auth-token');
  return `https://domain.com/preview?url=${previewUrl}&uuid=${uuid}&cdnUrlModifiers=${cdnUrlModifiers}&fileName=${fileName}&someAuthToken=${yourAuthToken}`;
}

This function should return a signing proxy URL.

CSP settings

If your application handles sensitive user data (e.g., personal photos), we recommend enhancing its security through CSP settings. The File Uploader uses Blob URLs for on-the-fly image generation and stylesheets in some cases. Consequently, remember to add blob: as a source in the CSP settings:

<meta
  http-equiv="Content-Security-Policy"
  content="style-src 'self' blob:; script-src 'self'; img-src 'self' https://*.ucarecd.net https://ucarecdn.com blob:;"
/>

ucarecdn.com is kept for legacy purposes only; use ucarecd.net going forward.