# CKBox Uploader widget configuration options

<a id="required-properties">

## Required Properties

| Property   | Type                 | Description                                                                                                                            |
| ---------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenUrl` | `string \| function` | The URL of the [token endpoint](../../../guides/configuration/authentication.md#token-endpoint) or a callback that provides the token. |

<a id="optional-properties">

## 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     |

<a id="property-details">

## Property Details

<a id="tokenurl">

### `tokenUrl`

**Type:** `string | function`\
**Required:** Yes

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

<a id="string-url">

#### String URL

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

<a id="callback-function">

#### Callback Function

```javascript
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
});
```

<a id="workspaceid">

### `workspaceId`

**Type:** `string`\
**Required:** No

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

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

<a id="uploadcategoryid">

### `uploadCategoryId`

**Type:** `string`\
**Required:** No

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

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

<a id="uploadfolderid">

### `uploadFolderId`

**Type:** `string`\
**Required:** No

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

```javascript
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.

<a id="onupload">

### `onUpload`

**Type:** `function`\
**Required:** No

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

```javascript
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
});
```

<a id="serviceorigin">

### `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.

```javascript
// 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
});
```

---

Full index of the CKBox documentation: [llms.txt](../../../../llms.txt)