身份验证

SDK 支持两种凭证类型。将 apiKey / api_key 或 accessToken / access_token 传给客户端构造函数 — 传输层自动处理请求头。

我该选哪种凭证？

选择取决于 Imbrace 在你的产品中扮演什么角色：

在 Imbrace 之上开发 → 使用 Access Token

Imbrace 就是你的后端。你的终端用户登录 Imbrace（通过 OTP 或密码），他们的 acc_... access token 就是 SDK 在每个请求发出的凭证。Imbrace 的身份验证、数据库、业务逻辑（assistants、knowledge hubs、workflows、AI agents）全都以该登录用户的身份执行。

典型产品：chat widget、dashboard 或 mobile app，每位用户即为 Imbrace 的用户。Imbrace 自动以该 user 为单位记录 history、permissions 与审计记录。

包装 Imbrace → 使用 API Key

你有自己的后端、自己的用户、自己的数据库。Imbrace 只是你服务调用的其中一项能力 — “用 Imbrace 的 AI 回答这个” — 与你正在做的其他事并列。你的终端用户完全不知道 Imbrace 存在；你的服务以一组由 Imbrace org 管理员发放的 org 级 api_... key 调用 Imbrace。Imbrace 只看到一个身份（API key 对应的 service account），per-user attribution 由你自己负责。

典型产品：现有的 CRM、客服系统或内部工具，把 Imbrace 嵌入为一项功能。一组凭证放在 env file 里服务所有请求。

	在 Imbrace 之上开发（Access Token）	包装 Imbrace（API Key）
由谁执行 auth？	Imbrace（OTP／密码登录）	你（你自己的 auth）
谁的用户？	Imbrace 的 user	你的 user
以谁的 DB 为主？	Imbrace 的	你的
Imbrace 看到的身份	真实的终端用户	一个 service account
上游 per-user 审计	内置	由你处理
凭证存活时间	session 内；按需刷新	长期；不会自行过期
发送的请求头	`x-access-token: acc_...`	`x-api-key: api_...`

两种凭证均为一级支持。大部分资源接受两者。少数依赖用户上下文的功能（document artifacts、各 user 自己的 chat history）只在 access token 模式下有意义。

请求头对照

凭证	发送的请求头
`apiKey` / `api_key`	`x-api-key: api_xxx...`
`accessToken` / `access_token`	`x-access-token: acc_xxx...`

Org context 内嵌在凭证本身 — 每个 API key 与每个 access token 都绑定到唯一一个 org。Gateway 从你发出的凭证即可解析 org，完全不需要传 organizationId / organization_id 给 SDK。

分步骤设置凭证（env vars、dotenv、secrets），参阅安装指南。

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

如果你已有 acc_... token，直接传入：

TypeScript
Python

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

client = ImbraceClient(
    access_token="acc_xxxxxxxxxxxxx",
)

OTP 登录流程

使用此流程通过邮箱 OTP 验证用户并获取 session token。SDK 在登录成功后自动存储 token。

TypeScript
Python

import { ImbraceClient } from "@imbrace/sdk"

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

// 步骤 1：向用户邮箱发送 OTP
await client.requestOtp("user@example.com")

// 步骤 2：用户提交收到的 OTP
const loginRes = await client.loginWithOtp("user@example.com", "ABC123")

// 步骤 3：换取长期有效的 access token
const { token, refresh_token } = await client.auth.exchangeAccessToken("org_your_org_id")

// 步骤 4：激活 token 用于后续所有调用
client.setAccessToken(token)

// 现在使用任何资源
const { data: boards } = await client.boards.list()

from imbrace import ImbraceClient

client = ImbraceClient()

# 步骤 1：向用户邮箱发送 OTP
client.request_otp("user@example.com")

# 步骤 2：用户输入 OTP — token 自动保存
client.login_with_otp("user@example.com", "123456")

# 步骤 3：后续所有调用已完成认证
me = client.platform.get_me()

异步变体：

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()

密码登录

TypeScript
Python

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

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

// Token 自动存储 — 使用任何资源
const { data: boards } = await client.boards.list()

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

# Token 自动存储
boards = client.boards.list()

Token 管理

TypeScript
Python

// 替换 token（例如刷新后）
client.setAccessToken("acc_new_token...")

// 清除 token（例如登出时）
client.clearAccessToken()

# 替换 token（例如刷新后）
client.set_access_token("acc_new_token...")

# 清除 token（例如登出时）
client.clear_access_token()

上下文管理器（仅 Python）

始终将 Python 客户端包装在上下文管理器中，以确保底层 httpx 连接池被正确关闭：

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

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