Setup Guide

This guide covers everything you need to go from zero to a working Imbrace SDK integration — installation, environments, credentials, and service URL overrides.

System Requirements

Requirement	Minimum version
Node.js	18.0.0+
npm	8.0.0+
Python	3.9+
pip	23.0+

Installation

TypeScript
Python

From npm registry:

npm install @imbrace/sdk
# or
yarn add @imbrace/sdk
# or
pnpm add @imbrace/sdk

Monorepo / local development:

# Step 1 — install dependencies and build
cd ts
npm install
npm run build

# Step 2 (optional) — link globally to use in another project on the same machine
npm link

Then in your external project:

npm link @imbrace/sdk

Verify:

import { ImbraceClient } from "@imbrace/sdk";
console.log("SDK loaded:", typeof ImbraceClient); // 'function'

From PyPI:

pip install imbrace
# or
uv add imbrace

Monorepo / local development (editable mode):

cd py
pip install -e ".[dev]"

The [dev] flag installs: pytest, pytest-asyncio, pytest-httpx, ruff, mypy.

Verify:

from imbrace import ImbraceClient
print("SDK loaded:", ImbraceClient)

Environments

Name	Gateway URL	Use when
`develop`	`https://app-gateway.dev.imbrace.co`	Internal development
`sandbox`	`https://app-gateway.sandbox.imbrace.co`	Integration testing
`stable`	`https://app-gatewayv2.imbrace.co`	Production (default)

Switch environments via the env constructor option, or override the URL directly with baseUrl:

TypeScript
Python

const client = new ImbraceClient({ env: "sandbox" });

client = ImbraceClient(env="sandbox")

Configure Credentials

Create a `.env` file

The SDK does not auto-read environment variables — you pass credentials directly to the constructor. A .env file is a user convention for storing secrets; use dotenv or your framework’s env loader to read them.

# Credentials
IMBRACE_API_KEY=your_api_key_here
IMBRACE_ACCESS_TOKEN=your_jwt_token_here

# Organization ID — sent with every request
IMBRACE_ORGANIZATION_ID=your_org_id_here

# Optional: override the gateway URL directly
IMBRACE_GATEWAY_URL=https://app-gatewayv2.imbrace.co

Get an API Key

See Get an API Key for full instructions.

Initialize the Client

import { ImbraceClient } from "@imbrace/sdk";

// Server-side — API Key
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env:            "stable",
});

// Client-side — Access Token (e.g. after a previous login, or a token you store yourself)
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env:         "stable",
});

// Password login (POST /v1/login/sign_in) — most common for end-user apps.
// Returns { token: "login_acc_...", organizations: [...] } in one call; pick one
// with selectOrganization() and the SDK swaps for an org-scoped acc_ token.
const anon = new ImbraceClient({ env: "stable" });
const { organizations } = await anon.login("user@example.com", "password");
await anon.selectOrganization(organizations[0].id);

// OTP login flow (alternative — for email-OTP UX instead of password)
await anon.requestOtp("user@example.com");
await anon.loginWithOtp("user@example.com", "123456");
// Token is stored automatically on the client

import os
from imbrace import ImbraceClient

# Server-side — API Key
client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
)

# Client-side — Access Token
client = ImbraceClient(
    access_token="eyJhbGci...",
    organization_id="org_xxx",
)

# Password login (POST /platform/v1/login/authenticate) — most common for end-user apps.
# login() returns the user's organizations; pick one and select_organization()
# swaps the short-lived login_acc_ token for an org-scoped acc_ token.
anon = ImbraceClient(env="stable")
res = anon.login("user@example.com", "password")
anon.select_organization(res["organizations"][0]["organization_id"])

# OTP login flow (alternative — for email-OTP UX instead of password)
anon.request_otp("user@example.com")
anon.login_with_otp("user@example.com", "123456")

from imbrace import AsyncImbraceClient

async def main():
    async with AsyncImbraceClient(api_key="api_...") as client:
        me = await client.platform.get_me()
        print(me)

CLI Installation

# Install globally
npm install -g @imbrace/cli

# Login to get started
imbrace login --api-key api_xxx...

See CLI Installation for alternative install methods and CLI Commands for the full command reference.

Override Service URLs

Use this when a microservice runs at a different address (e.g. local dev, dedicated staging).

TypeScript
Python

const client = new ImbraceClient({
  env: "develop",
  services: {
    aiAgent: "http://localhost:4000/ai-agent",
    dataBoard: "http://localhost:3001/data-board",
    channelService: "http://localhost:3002/channel-service",
  },
});

client = ImbraceClient(
    env="develop",
    services={
        "ai_agent":       "http://localhost:4000/ai-agent",
        "data_board":     "http://localhost:3001/data-board",
        "channel_service":"http://localhost:3002/channel-service",
    },
)

All valid service keys:

Python key	TypeScript key	Service
`gateway`	`gateway`	App Gateway
`platform`	`platform`	Platform service
`channel_service`	`channelService`	Channel service
`data_board`	`dataBoard`	Data Board
`backend`	`backend`	Legacy monolith (`/v1/backend`) — used for auth sign-in, templates, and a handful of routes not yet split out
`ips`	`ips`	IPS service
`ai`	`ai`	AI service
`marketplaces`	`marketplaces`	Marketplace service
`file_service`	`fileService`	File service
`message_suggestion`	`messageSuggestion`	Message Suggestion service
`predict`	`predict`	Predict service
`workflow_engine`	`workflowEngine`	Workflows
`ai_agent`	`aiAgent`	AI Agent service

Troubleshooting

`Cannot find package '@imbrace/sdk'`

Package is not linked. Re-run from ts:

npm link
cd /path/to/your-project && npm link @imbrace/sdk

`ERR_MODULE_NOT_FOUND` for files in `dist/`

Package has not been built yet:

cd ts && npm run build

`ModuleNotFoundError: No module named 'imbrace'`

cd py && pip install -e ".[dev]"

`401 Unauthorized`

API Key expired or invalid. Generate a new one from the Imbrace Dashboard or see the API Key guide.

`UserWarning: ImbraceClient: no credentials provided`

No api_key or access_token passed. If intentional (e.g. login-only flow), ignore this warning. Otherwise check your .env file.