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 API service. This allows you to use custom API endpoints or different service regions. This option should be set only if you host the CKBox backend on your own. It should not be present if you use CKBox in the SaaS version.

// Using default service
const ckbox = new CKBox({
 accessKey: process.env.CKBOX_ACCESS_KEY,
 environmentId: process.env.CKBOX_ENVIRONMENT_ID
 // serviceOrigin defaults to 'https://api.ckbox.io'
});
// Using custom endpoint
const customCkbox = 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