# Installation & Setup

This guide will walk you through installing and setting up the CKBox Node.js SDK in your project. By the end of this guide, you’ll have the SDK installed and be ready to make your first API calls.

<a id="prerequisites">

## Prerequisites

Before installing the CKBox Node.js SDK, ensure your environment meets these requirements:

* **Node.js**: Version 16.0.0 or higher
* **Package Manager**: npm, yarn, or pnpm
* **Module System**: ES modules support (the SDK is designed for modern Node.js applications)

<a id="package-installation">

## Package Installation

<a id="using-npm">

### Using npm

```bash
npm install @ckbox/sdk-node
```

<a id="using-yarn">

### Using yarn

```bash
yarn add @ckbox/sdk-node
```

<a id="using-pnpm">

### Using pnpm

```bash
pnpm add @ckbox/sdk-node
```

<a id="obtaining-access-credentials">

## Obtaining Access Credentials

Before you can use the SDK, you need to obtain your API credentials from the CKBox Customer Portal.

<a id="what-is-an-access-key">

### What is an Access Key?

The **Access Key** is a secret credential that authenticates your application with CKBox services. It’s used to generate JWT tokens that authorize API requests. This key should be kept secure and never exposed in client-side code.

<a id="getting-your-credentials">

### Getting Your Credentials

1. **Log in to Customer Portal**

   * Visit the [Customer Portal](https://portal.ckeditor.com/)
   * Sign in with your account credentials

2. **Navigate to API Credentials**

   * Go to the Subscription -> Cloud environments
   * Select “Access credentials” from the sidebar

3. **Create or Copy Access Key**

   * If you don’t have an access key, click “Create a new access key”
   * Copy your existing access key if you already have one

4. **Get Environment ID**

   * In the Cloud environments tab copy the Environment ID for the environment you want to use
   * You can have multiple environments (e.g., development, staging, production)

<a id="security-best-practices">

### Security Best Practices

⚠️ **Never commit your access key to version control**

Store your credentials using environment variables:

```bash
# .env file (add to .gitignore)
CKBOX_ACCESS_KEY=your_access_key_here
CKBOX_ENVIRONMENT_ID=your_environment_id_here
```

<a id="basic-setup">

## Basic Setup

<a id="1-import-the-sdk">

### 1. Import the SDK

```javascript
// ES modules (recommended)
import CKBox from '@ckbox/sdk-node';

// CommonJS (if needed)
const { default: CKBox } = require('@ckbox/sdk-node');
```

<a id="2-configure-environment-variables">

### 2. Configure Environment Variables

Create a `.env` file in your project root:

```bash
# Required credentials
CKBOX_ACCESS_KEY=your_access_key_here
CKBOX_ENVIRONMENT_ID=your_environment_id_here

# Optional settings
CKBOX_WORKSPACE_ID=your_workspace_id
CKBOX_SERVICE_ORIGIN=https://api.ckbox.io
```

<a id="3-initialize-the-sdk">

### 3. Initialize the SDK

```javascript
import CKBox from '@ckbox/sdk-node';
import 'dotenv/config'; // Load environment variables

// Basic configuration
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
});

// Access the main components
const { uploader, assets } = ckbox;
```

<a id="step-by-step-first-implementation">

## Step-by-Step First Implementation

Let’s create a complete example that demonstrates uploading a file and retrieving it:

<a id="1-create-project-structure">

### 1. Create Project Structure

```bash
mkdir ckbox-example
cd ckbox-example
npm init -y
npm install @ckbox/sdk-node dotenv
```

<a id="2-bootstrap-ckbox-object">

### 2. Bootstrap CKBox object

```javascript
// upload-example.js
import 'dotenv/config';
import fs from 'fs';
import CKBox from '@ckbox/sdk-node';

export const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  // Optional: specify user context
  userId: 'user-123',
  userName: 'John Doe',
  role: 'user'
});
```

<a id="3-create-your-first-upload-script">

### 3. Create Your First Upload Script

```javascript
// upload-example.js
...

async function uploadFile() {
  try {
	// Upload a file with progress tracking
	console.log('Starting file upload...');
	
	const result = await ckbox.uploader.uploadFile('./sample-image.jpg', {
	  onProgress: (progress) => {
		console.log(`Upload progress: ${progress.progress}%`);
	  }
	});
	
	console.log('Upload successful!');
	console.log('Asset ID:', result.id);
	console.log('File URL:', result.url);
	
	return result;
  } catch (error) {
	console.error('Upload failed:', error.message);
	throw error;
  }
}

// Run the upload
uploadFile()
  .then(asset => {
	console.log('✅ Upload completed successfully');
  })
  .catch(error => {
	console.error('❌ Upload failed:', error);
  });
```

<a id="4-test-your-setup">

### 4. Test Your Setup

```bash
# Add a test image to your project directory
# Run the upload script
node upload-example.js
```

---

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