Codiris
BlogLog in
Back to Docs

Getting Started

Install the SDK, set up authentication, and create your first board in minutes.

Installation

# npm
npm install codiris-brainboard-sdk

# yarn
yarn add codiris-brainboard-sdk

# pnpm
pnpm add codiris-brainboard-sdk

Requirements: Node.js 16+ and React 18+ (for React components, optional).

Quick Start

Vanilla JavaScript/TypeScript

import { BrainboardClient } from 'codiris-brainboard-sdk';

// 1. Initialize the client
const client = new BrainboardClient({
  apiKey: 'your-api-key',
});

// 2. Create a board
const { data: board } = await client.createBoard({
  name: 'My First Board',
});

// 3. Add a sticky note
await client.createObject(board.id, {
  type: 'sticky',
  x: 100,
  y: 100,
  width: 200,
  height: 200,
  text: 'Hello Brainboard!',
  fill: '#ffeb3b',
});

console.log(`Board created: ${board.id}`);

React

import {
  BrainboardProvider,
  BrainboardEmbed,
  useBoards
} from 'codiris-brainboard-sdk/react';

// 1. Wrap your app with the provider
function App() {
  return (
    <BrainboardProvider config={{ apiKey: 'your-api-key' }}>
      <WhiteboardPage />
    </BrainboardProvider>
  );
}

// 2. Use hooks and components
function WhiteboardPage() {
  const { boards, loading, createBoard } = useBoards();
  const [selectedBoard, setSelectedBoard] = useState(null);

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      <button onClick={() => createBoard({ name: 'New Board' })}>
        Create Board
      </button>

      {selectedBoard && (
        <BrainboardEmbed
          boardId={selectedBoard.id}
          width="100%"
          height="600px"
        />
      )}
    </div>
  );
}

Authentication

Getting an API Key

  1. Go to Codiris Settings
  2. Navigate to Settings & Members → API Keys
  3. Click Create Key in the "Brainboard SDK Keys" section
  4. Give your key a name (e.g., "Production", "Development")
  5. Optionally, configure allowed domains for security
  6. Copy the generated key - it will only be shown once!

Key Format

SDK keys have the format: brb_live_xxxxxxxxxxxxxxxxxxxx (or brb_test_ for test keys)

Using the API Key

const client = new BrainboardClient({
  apiKey: 'brb_live_your-api-key-here',
});

Environment Variables

Store your API key securely:

# .env
BRAINBOARD_API_KEY=brb_live_xxxxxxxxxxxxxxxxxxxx
const client = new BrainboardClient({
  apiKey: process.env.BRAINBOARD_API_KEY,
});

User Isolation (Multi-tenancy)

When embedding Brainboard in your application, you can isolate boards per user using the externalUserId feature. This allows each user in your system to have their own private set of boards.

How It Works

  1. Pass your user's unique ID as externalUserId when initializing the client
  2. When creating boards, they are automatically tagged with this external user ID
  3. When listing boards, only boards belonging to that user are returned

Example: Per-User Board Isolation

// Initialize client with your user's ID
const client = new BrainboardClient({
  apiKey: process.env.BRAINBOARD_API_KEY,
  externalUserId: currentUser.id, // Your application's user ID
});

// This user only sees their own boards
const { data: boards } = await client.listBoards();

// Boards created are tagged with this user's ID
const { data: board } = await client.createBoard({
  name: "User's Board",
});
// board.externalUserId === currentUser.id

React Provider with User Isolation

function App({ currentUser }) {
  const config = {
    apiKey: process.env.REACT_APP_BRAINBOARD_API_KEY,
    externalUserId: currentUser.id, // Each user sees only their boards
  };

  return (
    <BrainboardProvider config={config}>
      <BoardList />
    </BrainboardProvider>
  );
}

Note: The externalUserId is passed via the X-External-User-Id header in API requests.

Your First Board

Creating a Board

const { success, data: board, error } = await client.createBoard({
  name: 'Project Planning',
  description: 'Q1 2024 roadmap planning session',
  isPublic: false,
  settings: {
    gridEnabled: true,
    snapToGrid: true,
    allowComments: true,
  },
});

if (success) {
  console.log('Board created:', board.id);
} else {
  console.error('Failed:', error);
}

Fetching a Board

const { data: board } = await client.getBoard('board-id');

console.log(board.name);
console.log(board.createdAt);
console.log(board.settings);

Listing Your Boards

const { data } = await client.listBoards({
  status: 'active',    // 'active' or 'archived'
  search: 'project',   // Search by name
  page: 1,
  pageSize: 20,
});

console.log(`Found ${data.total} boards`);
data.items.forEach(board => {
  console.log(`- ${board.name} (${board.id})`);
});

Adding Objects

Sticky Notes

await client.createObject(boardId, {
  type: 'sticky',
  x: 100,
  y: 100,
  width: 200,
  height: 200,
  text: 'Important idea!',
  fill: '#ffeb3b', // Yellow
});

Text

await client.createObject(boardId, {
  type: 'text',
  x: 100,
  y: 100,
  text: 'Welcome to the board',
  fontSize: 32,
  fontWeight: 'bold',
  fill: '#1a1a1a',
});

Shapes

// Rectangle
await client.createObject(boardId, {
  type: 'shape',
  shapeType: 'rectangle',
  x: 100,
  y: 100,
  width: 200,
  height: 100,
  fill: '#3b82f6',
  stroke: '#1d4ed8',
  strokeWidth: 2,
});

// Circle
await client.createObject(boardId, {
  type: 'shape',
  shapeType: 'circle',
  x: 350,
  y: 100,
  width: 100,
  height: 100,
  fill: '#22c55e',
});

Batch Creation

Create multiple objects at once for better performance:

await client.createObjects(boardId, [
  { type: 'sticky', x: 100, y: 100, text: 'Task 1', fill: '#fef08a' },
  { type: 'sticky', x: 320, y: 100, text: 'Task 2', fill: '#fef08a' },
  { type: 'sticky', x: 540, y: 100, text: 'Task 3', fill: '#fef08a' },
]);

React Integration

Provider Setup

Wrap your app with the provider at the root level:

// app.tsx or index.tsx
import { BrainboardProvider } from 'codiris-brainboard-sdk/react';

function App() {
  const config = {
    apiKey: process.env.REACT_APP_BRAINBOARD_API_KEY,
    workspaceId: 'optional-workspace-id',
  };

  return (
    <BrainboardProvider config={config}>
      <Router>
        <Routes />
      </Router>
    </BrainboardProvider>
  );
}

Embedding a Board

import { BrainboardEmbed } from 'codiris-brainboard-sdk/react';

function BoardEditor({ boardId }) {
  return (
    <BrainboardEmbed
      boardId={boardId}
      width="100%"
      height="calc(100vh - 64px)"
      showToolbar
      showSidebar
      theme="light"
      onReady={() => console.log('Board loaded!')}
      onBoardChange={(board) => console.log('Updated:', board)}
    />
  );
}

Using Hooks

import { useBoard, useBoardObjects } from 'codiris-brainboard-sdk/react';

function BoardDetails({ boardId }) {
  const { board, loading, error, updateBoard } = useBoard(boardId);
  const { objects, createObject } = useBoardObjects(boardId);

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  const addNote = () => {
    createObject({
      type: 'sticky',
      x: Math.random() * 500,
      y: Math.random() * 500,
      text: 'New note',
    });
  };

  return (
    <div>
      <h1>{board.name}</h1>
      <p>{objects.length} objects on this board</p>
      <button onClick={addNote}>Add Note</button>
    </div>
  );
}

Next Steps

API Reference

Complete SDK method documentation

React Components

All React components and hooks

Object Types

Detailed object type reference

Examples

Code examples and recipes