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.

Type: string
Required: Yes

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

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:

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

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).

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

Type: string
Required: No

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

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

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

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

Type: string
Required: No

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

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

Type: string
Required: No

A human-readable name for the user.

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

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.

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