Xác Thực

SDK hỗ trợ hai loại credential. Truyền apiKey / api_key hoặc accessToken / access_token vào constructor — transport tự xử lý headers.

Nên Dùng Credential Nào?

Lựa chọn tuỳ thuộc vào vai trò của Imbrace trong sản phẩm của bạn:

Build trên Imbrace → dùng Access Token

Imbrace là backend của bạn. End-user của bạn đăng nhập vào Imbrace (qua OTP hoặc password); token acc_... của họ chính là credential mà SDK gửi đi trên mỗi request. Auth, database, và business logic của Imbrace (assistants, knowledge hubs, workflows, AI agents) đều chạy thay mặt cho user đăng nhập đó.

Sản phẩm điển hình: chat widget, dashboard, hoặc mobile app — mỗi user là một user trong Imbrace. Imbrace tự ghi nhận history, permissions, và audit trail theo từng user.

Wrap Imbrace → dùng API Key

Bạn có backend riêng, user riêng, database riêng. Imbrace chỉ là một capability mà service của bạn gọi tới — “dùng AI của Imbrace để trả lời câu này” — bên cạnh nhiều thứ khác bạn đang làm. End-user của bạn không biết Imbrace tồn tại; service của bạn gọi Imbrace bằng một api-key cấp org (api_...) duy nhất (do admin org của Imbrace cấp). Imbrace chỉ thấy một danh tính (service account của API key) và bạn tự lo phần per-user attribution ở phía mình.

Sản phẩm điển hình: CRM có sẵn, hệ thống ticketing, hoặc internal tool nhúng Imbrace như một feature. Một credential duy nhất nằm trong env file phục vụ tất cả request.

	Build trên Imbrace (Access Token)	Wrap Imbrace (API Key)
Ai chạy auth?	Imbrace (OTP / password login)	Bạn (auth của bạn)
User của ai?	User của Imbrace	User của bạn
DB nào là canonical?	Của Imbrace	Của bạn
Imbrace thấy danh tính nào	End-user thực sự	Một service account
Per-user attribution trên server	Có sẵn	Bạn tự xử lý
Thời hạn credential	Theo session; refresh khi cần	Lâu dài; không tự hết hạn
Header gửi đi	`x-access-token: acc_...`	`x-api-key: api_...`

Cả hai credential đều được hỗ trợ đầy đủ. Hầu hết resources nhận cả hai. Một số tính năng phụ thuộc user context (document artifacts, chat history per-user) chỉ có ý nghĩa khi dùng access token.

Tham Chiếu Header

Credential	Header gửi đi
`apiKey` / `api_key`	`x-api-key: api_xxx...`
`accessToken` / `access_token`	`x-access-token: acc_xxx...`

Org context được mã hoá ngay trong chính credential — mỗi API key và mỗi access token đều cố định với một org duy nhất. Gateway resolve org trên mỗi request từ chính credential bạn gửi. Bạn không bao giờ cần truyền organizationId / organization_id cho SDK.

Để thiết lập credentials từng bước (env vars, dotenv, secrets), xem Hướng Dẫn Cài Đặt.

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

const client = new ImbraceClient({
  apiKey: "api_xxx...",
  baseUrl: "https://app-gatewayv2.imbrace.co",
});

import os
from imbrace import ImbraceClient

client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
)

Access Token

Nếu bạn đã có token acc_..., truyền trực tiếp:

TypeScript
Python

const client = new ImbraceClient({
  accessToken: "acc_xxxxxxxxxxxxx",
  baseUrl: "https://app-gatewayv2.imbrace.co",
});

client = ImbraceClient(
    access_token="acc_xxxxxxxxxxxxx",
)

Dùng luồng này để xác thực user qua email OTP và lấy session token. SDK tự lưu token sau khi đăng nhập thành công.

TypeScript
Python

import { ImbraceClient } from "@imbrace/sdk"

const client = new ImbraceClient({
  baseUrl: "https://app-gatewayv2.imbrace.co",
})

// Bước 1: Gửi OTP đến email người dùng
await client.requestOtp("user@example.com")

// Bước 2: Người dùng nhập OTP — token được lưu tự động
const loginRes = await client.loginWithOtp("user@example.com", "ABC123")

// Bước 3: Đổi lấy long-lived access token
const { token, refresh_token } = await client.auth.exchangeAccessToken("org_your_org_id")

// Bước 4: Kích hoạt token cho tất cả các call tiếp theo
client.setAccessToken(token)

// Giờ dùng bất kỳ resource nào
const { data: boards } = await client.boards.list()

from imbrace import ImbraceClient

client = ImbraceClient()

# Bước 1: Gửi OTP đến email người dùng
client.request_otp("user@example.com")

# Bước 2: Người dùng nhập OTP — token được lưu tự động
client.login_with_otp("user@example.com", "123456")

# Bước 3: Tất cả các call tiếp theo đã được xác thực
me = client.platform.get_me()

Phiên bản async:

from imbrace import AsyncImbraceClient

async with AsyncImbraceClient() as client:
    await client.request_otp("user@example.com")
    await client.login_with_otp("user@example.com", "123456")
    me = await client.platform.get_me()

Đăng Nhập Bằng Password

TypeScript
Python

const client = new ImbraceClient({
  baseUrl: "https://app-gatewayv2.imbrace.co",
})

await client.login("user@example.com", "password")

// Token được lưu tự động — dùng bất kỳ resource nào
const { data: boards } = await client.boards.list()

client = ImbraceClient()
client.login("user@example.com", "password123")

# Token được lưu tự động
boards = client.boards.list()

Quản Lý Token

TypeScript
Python

// Thay token (ví dụ: sau khi refresh)
client.setAccessToken("acc_new_token...")

// Xóa token (ví dụ: khi logout)
client.clearAccessToken()

# Thay token (ví dụ: sau khi refresh)
client.set_access_token("acc_new_token...")

# Xóa token (ví dụ: khi logout)
client.clear_access_token()

Context Manager (Chỉ Python)

Luôn wrap Python client trong context manager để HTTP connection pool được đóng đúng cách:

# Synchronous
with ImbraceClient(api_key="api_xxx") as client:
    me = client.platform.get_me()

# Asynchronous
async with AsyncImbraceClient(api_key="api_xxx") as client:
    me = await client.platform.get_me()