---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - authentication
  - audit
topic: LangSmith Smith API API Keys、登录、SSO、审计与 Marketplace
sources:
  - https://docs.langchain.com/langsmith/smith-api/api-key/delete-api-key
  - https://docs.langchain.com/langsmith/smith-api/api-key/delete-personal-access-token
  - https://docs.langchain.com/langsmith/smith-api/api-key/generate-api-key
  - https://docs.langchain.com/langsmith/smith-api/api-key/generate-personal-access-token
  - https://docs.langchain.com/langsmith/smith-api/api-key/get-api-keys
  - https://docs.langchain.com/langsmith/smith-api/api-key/get-personal-access-tokens
  - https://docs.langchain.com/langsmith/smith-api/audit-logs/get-audit-logs
  - https://docs.langchain.com/langsmith/smith-api/auth/check-sso-email-verification-status
  - https://docs.langchain.com/langsmith/smith-api/auth/confirm-sso-user-email
  - https://docs.langchain.com/langsmith/smith-api/auth/get-public-auth-info
  - https://docs.langchain.com/langsmith/smith-api/auth/get-sso-settings
  - https://docs.langchain.com/langsmith/smith-api/auth/login
  - https://docs.langchain.com/langsmith/smith-api/auth/lookup-sso-by-email
  - https://docs.langchain.com/langsmith/smith-api/auth/send-sso-email-confirmation
  - https://docs.langchain.com/langsmith/smith-api/aws_marketplace/aws-marketplace-fulfillment-url-registration
  - https://docs.langchain.com/langsmith/smith-api/organizations/get-current-organization-info
last_verified: 2026-08-11
---

# Smith API：API Key、登录 SSO、审计与 Marketplace

Smith API 的主机是 `https://api.smith.langchain.com`。常规 API 以 `X-Api-Key`、Tenant/Organization 上下文或 Bearer session 鉴权；OpenAPI 的 security 数组表示“其中任一方案”，并不代表可同时忽略资源作用域。公开 SSO/OIDC discovery 等端点明确为 `security: []`，只能返回完成认证所必需的最小信息。

## API Key 与 PAT

旧的 `/api/v1/api-key` 族提供创建、列表、删除 API key：

| 操作 | 方法与路径 | 关键字段 |
|---|---|---|
| 创建 | `POST /api/v1/api-key` | description、read_only、expires_at、workspaces、role_id、org_role_id、default_workspace_id |
| 列表 | `GET /api/v1/api-key` | 返回 metadata，不返回完整 key |
| 删除 | `DELETE /api/v1/api-key/{api_key_id}` | UUID path |

创建响应在 `APIKeyCreateResponse.key` 只给出完整 secret；常规响应只有 `short_key`、last used、expiry、workspace/role 信息。必须在创建时立即进入 secret manager，之后不能依赖 list 取回。

`/api/v1/api-key/current` 的 create/list/delete PAT 三个入口已标记 **deprecated**，替代入口是 `/api/v1/orgs/current/personal-access-tokens`。新集成不要继续绑定 deprecated path；迁移时保留旧 client 的读写兼容窗口，并对照响应 schema 后再切换。

生产 key 基线：

- 默认过期而不是永久 key；使用 workspace 与 role 最小作用域；只读任务设 `read_only=true`。
- 不在浏览器、URL、日志、trace input/output 或 notebook 中存 token。
- 轮换采用“新建 → 双 key 验证 → 切换 → 删除旧 key”，删除前查 `last_used_at`。
- API key ID、short key 和 secret 是不同字段；审计记录 ID/short key，不记录完整 secret。

## 登录与 SSO 发现

SSO 相关公开流程：

| 端点 | 鉴权 | 用途 |
|---|---|---|
| `POST /api/v1/login` | public | 登录入口 |
| `GET /api/v1/sso/settings/{sso_login_slug}` | public | 由 login slug 返回 provider/organization 摘要 |
| `POST /api/v1/sso/email-lookup` | public | 为 SCIM-provisioned email 查可用 SSO provider |
| `POST /api/v1/sso/email-verification/status` | public | email + SAML provider ID 查确认时间 |
| `POST /api/v1/sso/email-verification/confirm` | public | 用一次性 token 确认邮箱 |
| `POST /api/v1/sso/email-verification/send` | Bearer | 发送确认邮件 |
| `GET /auth/public` | workspace session | 返回当前 session 的 user/org/tenant IDs 与 email |

公开不等于无限制：email lookup/status/send 必须限流、防枚举、统一错误文案、短期一次性 token 与重放保护。`/auth/public` 名字包含 public，但 OpenAPI 要 API Key/Tenant/Bearer 之一；它只是“公开认证信息结构”，不是匿名接口。

Login/SSO client 不能只信前端传来的 organization、workspace 或 email。身份与资源关联必须在服务端从验证后的 session、SAML/OIDC claims 和组织配置解析。

## 当前 Organization 安全配置快照

`GET /api/v1/platform/orgs/current/info` 使用 Organization 上下文，返回的管理快照包含：

- SSO/JIT/invite/public sharing/PAT creation 开关；
- permissions、tier、workspace 上限、成员禁用状态；
- key/PAT/service key 最大有效期；
- SCIM group separator、security contact；
- IP allowlist 与是否启用；
- disabled model providers；
- LLM auth proxy 开关、audience 与 allowed URLs；
- managed eval consent、Engine enable 与月 LCU spend limit；
- BYOC、Marketplace payout 等 feature flags。

这是控制面状态，不应用作客户端长期缓存。管理 UI 应按 permission 隐藏/禁用操作，服务端仍必须逐请求授权；配置变更需记录旧值、新值、操作者与回滚计划。

## OCSF Audit Logs

`GET /api/v1/audit-logs` 按 organization 返回 OCSF API Activity（Class UID 6003），适合 SIEM。`start_time` 与 `end_time` 都必填且 inclusive；可按 workspace、operations 过滤，`limit` 1–100（默认 10），用 base64 JSON cursor 分页。

游标不应由客户端解码后篡改；日志采集要保存 checkpoint，处理重复页和超时重试。审计日志含敏感身份/操作上下文，导入 SIEM 时继续执行访问控制、保留期、加密与脱敏。

## AWS Marketplace 注册

`POST /aws-marketplace/register` 是 public multipart endpoint，接收必填 `x-amzn-marketplace-token`，解析 Marketplace customer 并写库，成功以 303 跳到 thank-you 页面；错误为 400/500。

该 token 必须服务端向 AWS 验证，不能信任表单值。需要防 CSRF/重放、限制 body、记录 AWS customer 与 organization 绑定的幂等键，并只允许预配置 redirect 目标，避免 open redirect。

## 错误与验证

OpenAPI 常见 422 是参数/schema 验证失败；OAuth/Go 路由还会明确给 400/401/403/404/5xx。客户端不要把所有非 2xx 解析成同一 JSON schema。日志与重试策略：

- 400/401/403/422：修请求或权限，不自动无限重试；
- 404：同时可能代表不存在、越权隐藏或已删除；
- 429/5xx/网络失败：只对幂等读取或有 idempotency key 的写操作做有界退避；
- 创建 secret/token 的响应若客户端超时，先查资源列表，不能盲目重建一批凭据。