# Configuration Options

The CKBox Node.js SDK provides a flexible configuration system that allows you to customize the SDK behavior to match your application’s requirements. This guide covers all available configuration options, their purposes, and usage examples.

<a id="required-properties">

## Required Properties

| Property        | Type     | Description                                                                                          |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `accessKey`     | `string` | The access key obtained from the Customer Portal                                                     |
| `environmentId` | `string` | The environment identifier that specifies which CKBox environment your application should connect to |

<a id="optional-properties">

## Optional Properties

| Property        | Type     | Description                             |
| --------------- | -------- | --------------------------------------- |
| `workspaceId`   | `string` | Workspace context for the user session  |
| `role`          | `string` | Permission level for the user session   |
| `userId`        | `string` | Unique identifier for the user          |
| `userName`      | `string` | Human-readable name for the user        |
| `serviceOrigin` | `string` | Sets the origin to use for the REST API |

<a id="property-details">

## Property Details

<a id="accesskey">

### `accessKey`

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

The access key obtained from the Customer Portal. This key is used to authenticate your application with CKBox services.

```javascript
const ckbox = new CKBox({
  accessKey: 'your-secret-access-key',
  // ... other options
});
```

**Important Security Notes:**

* Never expose this key in client-side code
* Store it as an environment variable
* Rotate keys regularly for enhanced security

**Example with environment variable:**

```javascript
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  // ... other options
});
```

<a id="environmentid">

### `environmentId`

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

The environment identifier that specifies which CKBox environment your application should connect to. Environments allow you to separate different stages of your application (development, staging, production).

```javascript
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: 'env_123456789',
});
```

**How to find your Environment ID:**

1. Log in to the Customer Portal
2. Navigate to “Subscription” -> “Cloud Environments”
3. Copy the ID from your desired environment

<a id="workspaceid">

### `workspaceId`

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

Specifies the workspace context for the user session. Workspaces provide data isolation in multi-tenant applications.

```javascript
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  workspaceId: 'workspace_user_123'
});
```

**Fallback behavior:**

* If not provided, operations will use the default workspace for the environment

<a id="role">

### `role`

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

Defines the permission level for the user session. Controls what operations the user can perform.

**Available roles:**

* `'user'` (default) - Basic role
* `'admin'` - Administrative permissions including category management
* `'superadmin'` - Full system permissions

```javascript
// User with basic permissions
const userCkbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  role: 'user'
});

// Admin with extended permissions
const adminCkbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  role: 'admin'
});
```

<a id="userid">

### `userId`

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

A unique identifier for the user. This is used for tracking, auditing.

```javascript
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  userId: 'user_12345',
  userName: 'John Doe'
});
```

<a id="username">

### `userName`

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

A human-readable name for the user.

```javascript
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  userId: 'user_12345',
  userName: 'John Doe'
});
```

<a id="serviceorigin">

### `serviceOrigin`

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

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

* 🇺🇸 **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
// US SaaS (default) — no serviceOrigin needed
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
  // serviceOrigin defaults to 'https://api.ckbox.io' (US-EAST-1)
});

// EU SaaS — set serviceOrigin to the EU region URL
const ckboxEu = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  serviceOrigin: 'https://api-eu.ckbox.io'
});

// On-premises — set serviceOrigin to your own backend URL
const ckboxOnPrem = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  serviceOrigin: 'https://{{self-hosted-ckbox}}.com'
});
```

**Default value:** `https://api.ckbox.io`

---

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