CKBox Uploader widget configuration options

Required Properties

Property	Type	Description
`tokenUrl`	`string \| function`	The URL of the token endpoint or a callback that provides the token.

Optional Properties

Property	Type	Description
`workspaceId`	`string`	A unique identifier of your CKBox workspace
`uploadCategoryId`	`string`	Target category for uploads
`uploadFolderId`	`string`	Target folder for uploads
`onUpload`	`function`	Callback triggered on successful upload
`language`	`string \| object`	UI language configuration
`serviceOrigin`	`string`	Sets the origin to use for the REST API

Property Details

`tokenUrl`

Type: string | function
Required: Yes

Authentication endpoint or callback function that provides JWT tokens for CKBox API access.

String URL

mountUploaderWidget(document.querySelector('#ckbox'), {
  tokenUrl: 'https://your-token-endpoint.com/auth',
  // ... other options
});

Callback Function

mountUploaderWidget(document.querySelector('#ckbox'), {
    tokenUrl: () =>
        new Promise((resolve, reject) => {
            const xhr = new XMLHttpRequest();

            xhr.open('GET', 'https://your.token.url');

            xhr.addEventListener('load', () => {
                const statusCode = xhr.status;
                const xhrResponse = xhr.response;

                if (statusCode < 200 || statusCode > 299) {
                    return reject(new Error('Cannot download new token!'));
                }

                return resolve(xhrResponse);
            });

            xhr.addEventListener('error', () => reject(new Error('Network Error')));
            xhr.addEventListener('abort', () => reject(new Error('Abort')));

            xhr.send();
        }),
  // ... other options
});

`workspaceId`

Type: string
Required: No

The unique identifier of your CKBox workspace. This determines which workspace the uploader widget will connect to.

mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  // ... other options
});

`uploadCategoryId`

Type: string
Required: No

Specifies the target category for uploads. Files will be uploaded directly to this category, respecting its file type restrictions.

mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  uploadCategoryId: 'images-category-id',
  // ... other options
});

`uploadFolderId`

Type: string
Required: No

Specifies the target folder for uploads. Files will be uploaded directly to this folder within the specified category.

mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  uploadFolderId: 'specific-folder-id',
  // ... other options
});

Note

If both uploadCategoryId and uploadFolderId are provided, the folder ID takes precedence and the category will be determined from the folder’s parent category.

`onUpload`

Type: function
Required: No

Callback function triggered when a file is successfully uploaded. Receives the uploaded asset data.

mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  onUpload: (asset) => {
    console.log('File uploaded:', asset);
    // Handle successful upload
    // asset contains: id, name, extension, url, size, etc.
  },
  // ... other options
});

`serviceOrigin`

Type: string
Required: No

Sets the REST API endpoint. CKBox SaaS operates in two geographic regions; on-premises installations use a custom URL.

Note

🇺🇸 US-EAST-1 (default): US SaaS customers do not need to set this option — the default https://api.ckbox.io already targets US-EAST-1.
🇪🇺 EU: EU SaaS customers must set serviceOrigin: 'https://api-eu.ckbox.io'.
On-premises: Set serviceOrigin to the URL of your self-hosted CKBox REST API.

// EU SaaS — set serviceOrigin to the EU region URL
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  serviceOrigin: 'https://api-eu.ckbox.io',
  // ... other options
});

// On-premises — set serviceOrigin to your own backend URL
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  serviceOrigin: 'https://your-ckbox-api.com',
  // ... other options
});