Chuyển đến nội dung
Imbrace SDK

Xác thực

SDK hỗ trợ hai loại thông tin xác thực. Truyền apiKey / api_key hoặc accessToken / access_token vào constructor client — tầng vận chuyển tự động xử lý các header.

Tôi nên sử dụng thông tin xác thực nào?

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

Build on Imbrace → sử dụng Access Token

Imbrace là backend của bạn. Người dùng cuối của bạn đăng nhập vào Imbrace (qua OTP hoặc mật khẩu); access token acc_... của họ là thông tin xác thực mà SDK sử dụng cho mọi yêu cầu. Xác thực, cơ sở dữ liệu và logic nghiệp vụ của Imbrace (AI agents, knowledge hubs, workflows) đều chạy thay mặt cho người dùng đã đăng nhập thực tế.

Sản phẩm điển hình: widget chat, dashboard, hoặc ứng dụng di động nơi danh tính của mỗi người dùng là người dùng Imbrace. Imbrace ghi lại lịch sử, quyền và nhật ký kiểm toán theo từng người dùng.

Wrap Imbrace → sử dụng API Key

Bạn có backend riêng, người dùng riêng, cơ sở dữ liệu riêng. Imbrace là một khả năng mà dịch vụ của bạn gọi đến — “dùng AI của Imbrace để trả lời câu này” — cùng với mọi thứ khác bạn làm. Người dùng cuối của bạn không bao giờ thấy Imbrace; dịch vụ của bạn gọi Imbrace bằng một key api_... cấp tổ chức duy nhất (do quản trị viên Imbrace cấp). Imbrace thấy một danh tính (người dùng dịch vụ của API key) và bạn tự xử lý việc ghi nhận theo từng người dùng ở phía bạn.

Sản phẩm điển hình: một CRM hiện có, hệ thống ticket, hoặc công cụ nội bộ nhúng Imbrace như một tính năng. Một thông tin xác thực nằm trong tệp env của bạn và phục vụ mọi yêu cầu.

Build on Imbrace (Access Token)Wrap Imbrace (API Key)
Ai chạy xác thực?Imbrace (đăng nhập OTP / mật khẩu)Bạn (xác thực riêng)
Người dùng của ai?Người dùng ImbraceNgười dùng của bạn
CSDL chính thức của ai?Của ImbraceCủa bạn
Danh tính Imbrace thấyNgười dùng cuối thực tếMột tài khoản dịch vụ
Ghi nhận theo người dùngTích hợp sẵnTùy bạn
Thời hạn thông tin xác thựcTheo phiên; làm mới khi cầnDài hạn; không tự hết hạn
Header được gửix-access-token: acc_...x-api-key: api_...

Cả hai loại thông tin xác thực đều là hạng nhất. Hầu hết các resource đều chấp nhận cả hai. Một số tính năng phụ thuộc vào ngữ cảnh người dùng (document artifacts, lịch sử chat theo người dùng) chỉ có ý nghĩa với access token.

Tham chiếu Header

Thông tin xác thựcHeader được gửi
apiKey / api_keyx-api-key: api_xxx...
accessToken / access_tokenx-access-token: acc_xxx...

Ngữ cảnh tổ chức được mã hóa bên trong chính thông tin xác thực — mọi API key và mọi access token đều gắn với chính xác một tổ chức. Cổng gateway phân giải tổ chức trên mọi yêu cầu từ thông tin xác thực bạn đã gửi. Bạn có thể tùy chọn ghi đè bằng cách truyền organizationId (TypeScript) hoặc organization_id (Python) vào constructor.

Để biết hướng dẫn thiết lập thông tin xác thực từng bước (env vars, dotenv, secrets), hãy xem Hướng dẫn thiết lập.

API Key

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


const client = new ImbraceClient({
  apiKey: process.env.IMBRACE_API_KEY,
  env: "stable",
});

Access Token

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

const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env: "stable",
});

Luồng đăng nhập OTP

Sử dụng luồng này để xác thực người dùng qua email OTP và lấy token phiên. SDK tự động lưu token sau khi đăng nhập.

Đăng nhập là quy trình đổi token hai giai đoạn:

  1. requestOtp → loginWithOtp cấp một token login_acc_... ngắn hạn (TTL 3 giờ). Token này chỉ làm được một việc: liệt kê các tổ chức mà người dùng thuộc về.
  2. selectOrganization(orgId) đổi nó lấy một token acc_... gắn với tổ chức đã chọn (TTL 30 ngày). Mọi lệnh gọi resource khác đều dùng token này.

Nếu người dùng chỉ thuộc đúng một tổ chức, bạn có thể bỏ qua bước chọn và truyền thẳng id tổ chức đó cho selectOrganization. Nếu họ thuộc nhiều tổ chức, hãy liệt kê và để người dùng chọn trước.

import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({
  env: "stable",
})


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


// Bước 2: Người dùng nhập OTP họ nhận được. SDK lưu token login_acc_...
//         ngắn hạn VÀ lấy danh sách tổ chức của người dùng trong cùng một lệnh gọi.
const { organizations } = await client.loginWithOtp("user@example.com", "ABC123")
const chosen = organizations[0]  // ← thay bằng lựa chọn từ UI của bạn


// Bước 3: Đổi token login_acc_ lấy token acc_ gắn với tổ chức.
//         SDK tự động cập nhật token nội bộ và x-organization-id.
await client.selectOrganization(chosen.id)


// Bây giờ sử dụng bất kỳ resource nào
const { data: boards } = await client.boards.list()

Lối tắt cho một tổ chức. Nếu id tổ chức đã được biết trước (ví dụ lưu trong IMBRACE_ORGANIZATION_ID), bạn có thể bỏ qua bước chọn và truyền thẳng cho selectOrganization. Bước chọn chỉ cần thiết khi người dùng thuộc nhiều tổ chức.

Đăng nhập bằng mật khẩu

login() trả về cả token đăng nhập và danh sách tổ chức của người dùng trong một lệnh gọi. Chọn một bằng selectOrganization() và SDK sẽ đổi token + header tổ chức giúp bạn.

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


// Bước 1: Đăng nhập. Trả về { token: "login_acc_...", organizations: [...] }.
const { organizations } = await client.login("user@example.com", "password")
const chosen = organizations[0]  // ← thay bằng lựa chọn từ UI của bạn


// Bước 2: Đổi login_acc_ lấy token acc_ gắn với tổ chức.
await client.selectOrganization(chosen.id)


// Bây giờ sử dụng bất kỳ resource nào
const { data: boards } = await client.boards.list()

Quản lý token

// Thay thế token (ví dụ: sau khi làm mới)
client.setAccessToken("acc_new_token...")


// Xóa token (ví dụ: khi đăng xuất)
client.clearAccessToken()

Context manager (chỉ Python)

Luôn bao bọc Python client trong context manager để pool kết nối httpx bên dưới được đóng sạch sẽ:

# Đồng bộ
with ImbraceClient(api_key=os.environ["IMBRACE_API_KEY"]) as client:
    me = client.platform.get_me()


# Bất đồng bộ
async with AsyncImbraceClient(api_key=os.environ["IMBRACE_API_KEY"]) as client:
    me = await client.platform.get_me()

Next steps