Smith API：Organization 生命周期、成员、权限、SSO 与计费

Organization 是账单、安全策略和多个 workspaces 的上层边界。/orgs/current/* 要 Organization ID 上下文；/orgs 的 list/create/pending invite 主要使用登录 Bearer。把 organization ID 当普通客户端参数而不验证，会直接形成跨租户越权。

创建、读取与邀请

POST /api/v1/orgs 创建 organization，必填：

display_name：至少 1 字符，仅字母数字、空格、-、_；
is_personal；
可选 security_contact email。

响应不仅有 ID/name/tier，还暴露 SSO/JIT/invite/public sharing、PAT、workspace-admin invite、key 有效期、IP allowlist、model provider、LLM proxy、Engine/managed eval 等配置。创建是高权限操作，应由控制面做幂等和配额校验。

GET /api/v1/orgs 列当前登录可见组织；skip_create=false 是默认参数，客户端若只想只读列举应显式评估它是否会触发平台的个人组织创建语义。GET/DELETE/POST /orgs/pending... 管理待加入组织并 claim invite，使用 Bearer；claim 前服务端必须把 invite 绑定当前 verified identity。

当前组织有两类详情：GET /orgs/current 返回账单连接/计划和权限，GET /orgs/current/info 返回配置控制面。不要根据字段名相近将两者互换。

成员与邀请状态机

stateDiagram-v2
    [*] --> Pending: invite single/batch
    Pending --> Active: claim / provisioning
    Pending --> Pending: patch role
    Pending --> [*]: delete invite
    Active --> Active: update role/profile
    Active --> [*]: remove member

主要端点：

单邀请 POST /orgs/current/members；批量 .../batch，最多 500；
Basic auth 批量新增 .../members/basic/batch，最多 500，可携 password/full_name；
active/pending 分页查询默认 50、最大 500，支持 email/name、user IDs、disabled、sort；
GET /orgs/current/members 一次返回 members + pending；
Platform enriched list 额外返回 workspace memberships、SCIM groups 与 login methods，支持 glob filters；
Pending patch 只改 role；Active patch 在各种 auth 模式改 role，basic auth 才改 full_name/password；当前 basic 用户另有 /orgs/members/basic。

批量接口可能部分成功或重复邀请，调用方要用 email/identity ID 做幂等、记录逐项结果，不把 HTTP 200 等同全部成功。删除成员前盘点其 service ownership、Agent、API key、workspace 和审计保留；不要先删用户再失去归属信息。

Roles 与 permissions

Organization roles 可 create/list/update/delete，schema 是 display name、description、permissions；返回 role ID/name、access scope 和 is_restricted。PUT /roles/{id}/restriction 单独切换 restricted 状态；GET /orgs/permissions 列平台可用 permission 与作用域。

Role update 要求完整 display name/description/permissions，不应按 merge patch 假设遗漏字段保留。删除 role 前检查成员、pending invites、PAT/service keys 和 workspace mappings 的引用。权限变更应采用 least privilege、双人复核和 before/after diff。

SSO provider create 需要：default workspace role ID、workspace IDs，以及 metadata XML 或 URL；支持 attribute mapping 与 group claim：

sso_groups_enabled；
claim field 默认 groups；
required 开关；
role sync 默认启用。

List/get/update/delete 都作用于 current organization。attribute_mapping_load_error 会随 provider 返回，配置成功不代表 metadata/映射可运行，必须做真实登录和 group sync 测试。

PATCH /orgs/current/login-methods 可设 sso_only；在确认 break-glass admin、metadata 可达、时钟与证书、SCIM/JIT、rollback 路径前不要打开。自托管的 set-default-sso-provision 指定默认 provisioning organization，切换会影响未显式匹配的用户，需要变更窗口。

Organization 配置 Patch

PATCH /orgs/current/info 可改：display name、public sharing/PAT/JIT/invite、workspace admin invite、key/PAT/service-key 最大天数、security contact、SCIM separator（恰好 1 字符）、LLM auth proxy/audience/allowed URLs、IP allowlist、disabled model providers、browser secret 限制、BYOC、Engine 与月 LCU limit。

unshare_all 是大范围撤销共享的高风险开关；IP allowlist、SSO-only、禁用 provider、LLM proxy URL、Engine spend 都可能让现有系统立即不可用。此接口不应由普通管理 UI 直接提交全对象；采用字段 allowlist、乐观锁/配置版本、dry-run 与回滚值。

PAT、service key 与 expiry policy

Organization 级 PAT/service key 的 create/list/delete 使用统一 APIKey schema：description、read_only、expiry、workspaces、workspace/org roles、default workspace。Service key 的 workspaces=null 表示 organization-wide，是权限放大的关键差异。

PATCH /service-keys/{id} 可在不轮换 secret 的情况下更新 role IDs，仅 org admin/ORGANIZATION_MANAGE 可用。权限变了但 secret 没变，审计必须记录这一点；若 secret 可能泄露，应 rotate/delete+create，而不是只改 role。

旧 /api-key/current PAT 已弃用，统一迁到本组 PAT endpoints。Organization 可通过 info 配置 max API key/PAT/service key expiry days，客户端创建前读取策略并避免超限。

Usage、billing 与 Stripe

能力	端点与语义
Billing snapshot	`GET /orgs/current/billing`，计划、payment method、period、transition
时间段 usage	`GET .../billing/usage`，`starting_on`、`ending_before`、current plan
granular usage	`GET .../granular-usage`，时间、workspace、group、kind、trace tier
CSV	`GET .../granular-usage/export`，同样的 filters
Dashboard	`GET /orgs/current/dashboard`，返回 embeddable URL

kind=traces 返回 traces，可按 longlived/shortlived retention tier；kind=langsmith_deployments 返回 nodes executed、Agent runs、uptime，traces 为 0。省略 workspace IDs 时只汇总用户可读 workspaces，避免列举过多 ID 导致 proxy header/URL 限制。

Stripe 流程包括 setup intent、payment method created、checkout session、account link 和 company/tax/invoice info。success_path 必须服务端 allowlist，不能开放任意 redirect；payment/plan 变更使用 provider webhook/服务端状态作为权威，不能只信前端回调。

价格/计划字段高度易变，业务系统不要把 tier enum 当永久合同。账单拉取按 UTC 边界，防重叠/遗漏；CSV 内容类型与列会随 kind 变化，不能固定解析一套列。

TTL 设置

GET/PUT /api/v1/orgs/ttl-settings 管理 organization 和可选 tenant 级 trace retention：default_trace_tier 必填，apply_to_all_projects 默认 false；返回 configured_by、longlived TTL days、timestamps。

TTL 是数据生命周期策略，不只是成本按钮。变更前评估已有 trace 是否立即受影响、合规保留、调查取证、评估数据引用与下游 export；对 all projects 开关执行双人审批。

生产执行顺序

用可信 Bearer/API key 解析 current organization，不接受前端任意 ID。
读取 permissions 与配置快照，按 API schema 做变更 diff。
对 SSO/IP/共享/role/key/billing/TTL 变更生成 dry-run 和依赖清单。
写入后重新 GET 验证，并用实际 member/session/key 做 canary。
审计 actor、organization、old/new、request ID、结果和 rollback；绝不记录密码、token、Stripe client secret。