LabArchives 认证与区域配置完全指南：基于 scientific-agent-skills 的 ELN 与 Inventory API 签名实战-平芜编程栈

LabArchives 认证与区域配置完全指南：基于 scientific-agent-skills 的 ELN 与 Inventory API 签名实战

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

LabArchives 是科研领域广泛使用的电子实验记录本（ELN）平台，其公开 API 采用一套独特且容易踩坑的认证体系：既不是常规的 OAuth 2.0，也不是简单的 API Token，而是基于 HMAC-SHA-512 的请求签名机制。本指南以 scientific-agent-skills 仓库中的labarchive-integrationSkill 为核心，系统讲解 LabArchives ELN 与 Inventory API v1 的访问前提、凭证类型、五区域主机映射、命名环境变量约定、用户授权（UID）流程、请求签名算法与安全规则，并给出可离线自检的命令行工具用法，帮助你在不泄露密钥的前提下安全接入 LabArchives 数据。

认证体系总览：先认清两套接口

LabArchives 提供两套文档化 API，它们在路径、认证载体和签名输入上完全不同，绝不能混用：

维度	传统 ELN API	Inventory API v1
覆盖范围	用户、笔记本、树、条目、附件、搜索、通知、站点许可工具	库存用户/实验室、物品、物品类型、订单、存储位置、供应商
路径形态	`/api/<class>/<method>`	`/public/v1/...`
认证载体	`akid`、`expires`、`sig`查询参数	`X-LabArchives-*`请求头
签名输入	仅 ELN 方法名	含已解析路径参数、不含查询字符串的精确相对路由
响应格式	多数方法返回 XML	端点页面提供 JSON Schema
版本标签	官方概览未显示公开版本号	`v1`

值得强调的是，官方文档描述的是一种OAuth 类似的（OAuth-like）重定向流程，官方资料中并没有通用 OAuth 2.0 的client_credentials、/oauth/authorize或/oauth/token端点；此外 Jupyter、REDCap、Protocols.io 等产品集成是各自的 UI 或文件工作流，不能作为存在通用 OAuth API 的证据。相关对照可参考 api_reference.md 与 SKILL.md。

访问前提：API 权限与产品订阅

ELN API：Enterprise 能力

根据官方 ELN 订阅指南（2025-09-24 更新），开发者 API 访问被列为Enterprise 能力。LabArchives 会为特定的组织/供应商及其指定用途签发一对Access Key ID 与 Access Password，它们不是普通的账号密码。要获取凭证，需联系所在机构的 LabArchives 团队或 LabArchives 支持，并取得随凭证一并提供的机构专属开发文档——当该文档与公开摘要不一致时，以机构文档为准。

Inventory API v1：Enterprise / Enterprise Plus 许可

Inventory FAQ（2026-05-19 更新）明确：API 访问仅向Enterprise 与 Enterprise Plus许可用户开放，且调用方必须同时满足：

拥有 LabArchives 账号；
拥有 Inventory 账号；
被授予 API 访问权限；
仍受 Inventory 应用访问权限约束。

符合条件的许可成员可通过support@labarchives.com申请访问。所有官方来源及其修订日期均记录在 sources.md 中。

六类凭证与身份标识：务必区分

原文档明确警告：不要在 API 脚本中使用普通的 LabArchives 账号密码。需要区分的值包括：

Access Key ID（akid）—— 标识 API 客户端本身。
Access Password—— HMAC-SHA-512 的签名密钥；永远不作为 API 参数或请求体字段发送。
UID—— 用户 ID，作用域限定于获取它的那个 Access Key ID；持久有效直至被吊销，但不能跨 API Key 移植。
授权码（Authorization code）—— 用户登录流程返回的短生命周期值，需立即通过users::user_access_info兑换。
临时密码令牌（Temporary password token）—— 由用户自行生成的替代值，可作为password参数传给users::user_access_info。
Inventory Lab ID—— 标识当前 Inventory 实验室，文档化名称为X-LabArchives-LabId。

区域主机映射：浏览器登录与 ELN API 刻意分离

LabArchives 为不同地区部署了独立的主机，且浏览器登录主机与 ELN API 主机是两类不同的域名，必须分开看。下表来自官方帮助中心 SSO 文章（2025-11-04 更新）与官方 ELN API 概览（2025-11-03 更新）：

区域	浏览器登录	ELN API URL
美国及世界其他地区	`https://mynotebook.labarchives.com`	`https://api.labarchives.com/api`
加拿大	`https://ca-mynotebook.labarchives.com`	`https://caapi.labarchives.com/api`
澳大利亚/新西兰	`https://au-mynotebook.labarchives.com`	`https://auapi.labarchives.com/api`
英国	`https://uk-mynotebook.labarchives.com`	`https://ukapi.labarchives.com/api`
英国以外的欧洲	`https://eu-mynotebook.labarchives.com`	`https://euapi.labarchives.com/api`

官方 ELN 概览建议分布式应用使用utilities::api_base_urls方法以动态发现未来新增的区域 API；而本 Skill 自带的校验器（validator）则有意将上述五个主机固定下来作为当前刷新日期（2026-07-23）的快照。这一约束在源码中有直接体现：setup_config.py 中的REGIONS字典精确登记了五组login_url与eln_api_url。

Inventory 绝对基础 URL：不要臆测

Inventory 的公开认证与端点页面只记录了相对的/public/v1/...路径及必需请求头，并未建立完整的区域绝对 API 基础 URL 表。官方资料虽然公开了 Inventory 浏览器主机，但浏览器主机不能证明 API 主机。务必使用机构/供应商开发文档中提供的 Inventory 基础 URL，切勿从登录 URL 反推 API URL。

命名环境变量约定与配置校验

本 Skill 的本地辅助工具约定使用以下五个环境变量名（这是 Skill 的本地约定，不是厂商定义的标准）：

LABARCHIVES_ELN_API_URL LABARCHIVES_ACCESS_KEY_ID LABARCHIVES_ACCESS_PASSWORD LABARCHIVES_USER_ID LABARCHIVES_INVENTORY_LAB_ID

建议通过 shell 会话、系统钥匙串、工作负载密钥仓库或机构批准的密钥管理器填充这些变量。配套脚本的行为有严格边界（见 setup_config.py 与 SKILL.md）：

只检查这五个精确名字；
从不向上遍历父目录寻找.env；
从不写密钥文件；
从不打印凭证值。

校验命令

在 Skill 目录下执行：

uv run scripts/setup_config.py check uv run scripts/setup_config.py check \ --require-user-id --require-inventory-lab-id

check子命令的行为可在 setup_config.py 中逐行核对：它默认要求LABARCHIVES_ACCESS_KEY_ID与LABARCHIVES_ACCESS_PASSWORD存在，--require-user-id追加要求LABARCHIVES_USER_ID，--require-inventory-lab-id追加要求LABARCHIVES_INVENTORY_LAB_ID；缺失任一必需变量时进程以退出码 2 结束，并输出missing_variables列表。它只做结构校验与变量存在性检查，不认证、不持久化、不打印凭证。

--prompt-missing-secret则使用getpass交互式获取缺失的 Access Password，且该值仅在内存中校验，不保存、不参与认证。这一行为同样在源码中明确实现（见 setup_config.py）。

端点结构的严格校验

normalize_eln_api_url（见 setup_config.py）会对 ELN API URL 施加硬约束，这些约束同样适用于--api-url参数与regions输出：

仅允许https，拒绝明文 HTTP；
拒绝在 URL 中内嵌用户名/密码；
拒绝自定义端口、查询字符串与片段；
路径必须严格为/api；
主机必须命中上述五区域白名单，否则报not allowlisted并列出候选。

regions子命令则直接输出带as_of: "2026-07-23"时间戳的五区域 JSON 清单，并附带"浏览器登录 URL 与 ELN API URL 不同、Inventory 绝对基础 URL 不由本工具推断"的警告。

ELN 用户授权流程：签名重定向 + UID 兑换

对于需要用户级数据的方法（多数方法都要求 UID），官方文档描述了一个OAuth 类似的签名重定向流程（官方用户登录页更新于 2023-03-03），步骤为：

选择用户所在区域的正确 ELN API 主机。
将用户重定向到该主机的/api_user_login路径，携带akid、expires、sig、redirect_uri参数。
对于这个特殊签名，必须使用未编码的精确重定向 URI代替普通的方法名作为签名输入。
LabArchives 完成账号/SSO 登录后，携带auth_code与email重定向回来。
立即调用文档化的users::user_access_info，把授权码作为其password参数、并传入返回的 email。
只把得到的 UID 存入经批准的安全存储；UID 与当前 Access Key ID 绑定且可被吊销。

如果无法使用重定向，官方流程也允许用户生成临时密码令牌填入同一password参数——务必通过getpass或安全 UI 字段处理，绝不要出现在命令行或日志中。

补充说明 UID 的三个特性（详见 api_reference.md）：它限定于获取它的 Access Key ID；持久有效直至吊销；可用于经批准的自登录设计。但不要用另一个 Access Key ID 复用 UID，也不要从账号信息中推断 UID。

请求签名算法：HMAC-SHA-512 与三种签名输入

官方调用认证页（2023-05-10 更新）给出的签名公式为：

message = AccessKeyID + api_method_input + expires signature = Base64(HMAC-SHA-512(key=AccessPassword, message=message))

关键点：

没有任何分隔符，三个部分直接拼接；
expires是当前时间的 Unix 毫秒时间戳（必要时按服务器时钟偏差校正），名字虽有误导性，但不是未来的令牌有效期；官方页面允许两分钟的延迟/轻微时钟同步余量，而最佳实践页建议时钟不可靠时使用utilities::epoch_time；
按接口类型区分api_method_input：
- ELN 普通调用：仅方法名，不含所属类（class）；
- ELN 用户登录重定向：未编码的重定向 URI；
- Inventory v1：精确相对路由，包含已解析的路径参数、排除查询字符串。

签名输入不可混淆

ELN 普通调用签的是方法名，而不是类::方法的完整写法——例如调entries::entry_info时签名输入只是entry_info；
ELN 与 Inventory 之间不能互搬认证载体：不要将 ELN 的查询参数认证搬进 Inventory 请求头，反之亦然；
Inventory 每次请求都要重新签名。

源码级验证：官方测试向量

entry_operations.py 中的create_signature以标准库hmac+hashlib.sha512精确实现了上述公式，并内嵌了官方公开的哑测试向量（见 entry_operations.py）：

message = f"{key_id}{method_input}{expires}".encode("utf-8") digest = hmac.new(secret.encode("utf-8"), message, hashlib.sha512).digest() return base64.b64encode(digest).decode("ascii")

测试套件 test_scripts.py 将这一实现与官方向量做已知答案测试（known-answer test）：test_the_official_vendor_vector_reproduces_exactly断言输出与官方签名完全一致；test_the_signature_is_base64_hmac_sha512_over_the_concatenation用独立方式重算签名，任何消息布局改动都会在测试中暴露，而不是等到 API 返回 401。

无需凭证、无需联网的自检

uv run scripts/entry_operations.py self-test

该命令使用官方发布的公共哑向量（Access Key ID 为0234wedkfjrtfd34er、Access Password 为1234567890）在本地验证签名实现，不发任何网络请求，输出仅含签名的 SHA-256 指纹（前 16 位十六进制），绝不会打印可复用的签名本身（见 entry_operations.py）。

离线请求规划：只出脱敏计划，不发真实请求

entry_operations.py刻意不携带任何 HTTP 客户端，只实现签名原语并输出脱敏的 JSON 计划：

# ELN 请求规划：验证类名/方法名合法、生成签名指纹 uv run scripts/entry_operations.py eln-plan \ --api-class entries --api-method entry_info # Inventory 请求规划：验证 /public/v1/... 相对路由 uv run scripts/entry_operations.py inventory-plan \ --path /public/v1/users/me

两个计划命令都会输出dry_run: true、remote_request_performed: false，并用指纹代替真实凭证与签名（见 entry_operations.py）。如果需要把签名逻辑集成到机构审查过的代码中，可以导入create_signature、build_eln_auth_params、build_inventory_headers函数，并把返回的认证材料直接传给 HTTP 客户端，绝不打印或持久化。

Inventory 路由校验的防御性细节

validate_inventory_path（见 entry_operations.py）在签名前会拒绝：

含?或#的路径（签名与发送内容不一致是重放/篡改风险）；
百分号编码或含空白的路径；
未解析的{id}占位符；
非/public/v1/前缀、包含./..段或双斜杠的路径。

对应测试位于 test_scripts.py。ELN 方法名则通过^[a-z][a-z0-9_]*$正则校验，禁止大写、连字符、空格与斜杠（见 entry_operations.py），这从机制上防止"凭直觉编造方法名"——官方当前类树中实际出现的示例方法包括users::user_access_info、users::user_info_via_id、entries::entry_info、entries::entry_attachment、notebooks::notebook_backup、utilities::epoch_time、utilities::api_base_urls等，详见 api_reference.md。

Inventory 认证头

Inventory v1 的认证页（2025-11-24 更新）文档化了五个必需请求头，build_inventory_headers（见 entry_operations.py）按序生成：

X-LabArchives-UId X-LabArchives-AKId X-LabArchives-LabId X-LabArchives-Signature X-LabArchives-Expires

在真正发起任何远程写入前，建议遵循 SKILL.md 中列出的安全序列：先打开精确的官方方法页核对动词/路径/参数/请求体/响应 Schema，再生成脱敏的 dry-run 计划，确认目标区域与笔记本/实验室及用户可见影响，取得明确批准后才发送，最后回读并核验结果对象——不能仅凭 HTTP 200 推断成功，因为部分方法文档化了响应体。Skill 自带的脚本本身不执行任何远程写入。