浏览器业务接口使用同源 JSON，前缀 /api。错误为 {"error":{"code":"...","message":"..."}}。请求体最多 2 MiB，有结构化字段的业务 JSON 拒绝未知字段。OIDC回调和SCIM机器接口使用下面单列的协议；外部互联不是这些管理 API 的别名。以下保留历史版本分节，实际运行版本须与候选源码分别核对。
企业身份接入补充
| 方法与路径 | 认证与支持范围 |
|---|---|
POST /oidc/start | 显式启用后发起固定IdP登录，state/nonce/PKCE |
GET /oidc/callback | 校验一次性回调、签名及精确主体映射，创建本地会话 |
POST /oidc/backchannel-logout | 签名logout_token；撤销匹配的OIDC会话，不等同停用本地人员 |
GET /scim/v2/ServiceProviderConfig | 独立配置的到期Bearer；说明受限机器接口能力 |
GET /scim/v2/Users、/scim/v2/Users/{id} | 单企业、明确OIDC映射的既有人；有界分页与精确过滤，不按邮箱合并 |
PATCH /scim/v2/Users/{id} | 仅一个replace active=false，可带If-Match；事务性停用和撤销全部本地会话/挑战，保护最后管理员 |
SCIM默认关闭，使用application/scim+json请求/响应及SCIM错误对象；仅接受专用机器Bearer，不以浏览器Cookie或CSRF令牌代替认证。最大4KiB单操作PATCH、每页最多100人，不支持开户、角色/组同步、Bulk、删除或active=true。服务不签发OAuth凭据，也未宣称完整SCIM实现。配置、停用副作用、重试和真实IdP条件见SCIM人员生命周期实施；原OIDC边界见产品操作手册。
浏览器业务接口
| 方法与路径 | 权限 / 内容 |
|---|---|
GET /health | PostgreSQL 就绪状态 |
POST /login | email,password；每进程按来源 IP 限制登录尝试 |
GET /me | 登录身份与 CSRF token |
POST /logout | 删除会话 |
POST /me/key | publicKey；只允许首次登记 |
GET /workspace | 所属空间、本机构连接器、允许发现的机构 |
POST /parties | 仅运营账号；name,email,password |
POST /spaces | name,description |
POST /spaces/{id}/members | 仅空间运营机构；partyId |
POST /connectors | name,publicKey |
POST /connectors/{id}/revoke | 仅所属机构，撤销服务请求权限 |
GET/POST /products | 列表 / 创建（必须提供 datasetVersionId、spaceId、name、description） |
POST /products/{id}/status | 所属机构；status=published/unpublished |
GET/POST /contracts | 合约双方列表 / productId,name,policy 创建 |
POST /contracts/{id}/revise | 待签合约双方；policy；旧签名不沿用 |
POST /contracts/{id}/challenge | 返回一次性签名挑战，2 分钟有效 |
POST /contracts/{id}/sign | challengeId,signature；Ed25519 签署挑战原文 |
POST /contracts/{id}/terminate | 合约任一方，停止任务并撤销后续访问 |
POST /contracts/{id}/jobs | 使用方；operation,field?,groupBy?；必须提供 Idempotency-Key |
GET /jobs | 合约双方任务；使用方审核前无 result |
POST /jobs/{id}/cancel | 双方取消排队/运行任务 |
POST /jobs/{id}/review | 提供方且jobs.review；approve 布尔值 |
POST /jobs/{id}/export | 使用方；合约允许导出+提供方准许+仍有效 |
GET /evidence?scope=... | 自身 party:ID 或有权访问的 contract:ID |
GET /capabilities | 认证后读取同版发布能力/任务清单及本企业链状态摘要；无节点凭据 |
| POST /interop/{operation} | 501，外部协议未配置 |
开发中的签名密钥轮换接口见密钥轮换开发记录。它们尚未部署到已验收v0.5.1，不应依据开发源码推断当前运行实例已启用遗失恢复。
浏览器会话使用 HttpOnly; SameSite=Strict Cookie；正式 HTTPS 配置还设置 Secure。所有登录后 POST 要求 X-CSRF-Token，并核验 Origin 白名单。反向代理不能把任意 X-Forwarded-* 值当作认证依据。
企业连接器协议
所有连接器接口均使用 POST，不接受浏览器 Cookie 作为服务认证：
/agent/claim返回一个任务或 null。/agent/jobs/{id}/heartbeat：leaseToken，续租至最多 30 秒或合约到期。/agent/jobs/{id}/complete：leaseToken,result,receipt,signature；后三项为结果 JSON 原文、回执 JSON 原文、回执签名。/agent/jobs/{id}/fail：leaseToken；仅记录固定失败原因，不回传可能含私密原始内容的错误。
请求头 X-Connector-ID、X-Timestamp（Unix 毫秒）、X-Nonce、X-Signature。Ed25519 签名载荷为以下字符串，UTF-8 编码，行尾不再补换行：
datanous-connector-v1
POST
完整RequestURI（包含查询参数）
毫秒时间戳
随机数
请求体SHA256十六进制时间偏差最多 30 秒，随机数存储在 PostgreSQL 中防重放；撤销的连接器即使签名正确也不能访问。非回环平台必须 HTTPS，客户端不跟随重定向。
回执绑定合约摘要、任务编号、租约令牌、结果摘要、输入文件摘要、输入条数、完成时间和固定执行器版本。成功提交可原样重试，不重复扣次；网络不明任务不会自动重新运行。连接器请求签名和回执签名证明登记密钥持有者提交了内容，不构成硬件远程证明。
额度与状态
PostgreSQL 行锁串行化同一合约的签署、修改、终止和使用计数；幂等键使用事务 advisory lock 和唯一约束。使用账本先 reserved，计算成功 committed，失败/取消 released。审核拒绝不退还已完成计算的次数。多次清理不会重复退款。
租约超时任务标记失败，必须由用户明确发起新的请求。合约终止同时 fence 运行任务，并在后续查看、审核、导出时复查授权。提供方可保留查看本方已计算结果；使用方权限随合约终止撤销。
企业内部资产 API
以下浏览器接口沿用 Cookie、CSRF 与 Origin 检查，数据严格按本企业隔离。JSON未知字段会被拒绝，不能把密码/DSN塞进配置登记。
| 方法与路径 | 请求与行为 |
|---|---|
GET /assets/catalog | 返回 sources、assets、datasets、pipelines、tasks；无原始数据行或服务租约令牌 |
POST /sources | name,connectorId,kind,configRef,classification,description；登记引用 |
POST /sources/{id}/scan | 提交企业侧资源发现 |
POST /assets/{id}/snapshot | 按固定资产结构生成企业侧数据集快照 |
POST /pipelines | name,inputs=[数据集版本ID],plan={steps,rules}；固定输入和规则，创建前校验字段 |
POST /pipelines/{id}/run | 使用固定输入版本运行；产生新输出版本 |
POST /asset-tasks/{id}/cancel | 取消排队/运行中的内部任务 |
POST /products 自v0.2要求 datasetVersionId；字段、连接器、分类和源引用从已验收版本派生，不能跨企业绑定、发布隔离版本或包含候选敏感字段的版本。已有v0.1产品保留执行兼容。
企业连接器通过相同签名认证访问：POST /agent/assets/claim、POST /agent/asset-tasks/{id}/heartbeat、/complete、/fail。续租/失败使用leaseToken；完成使用leaseToken,output,proof,signature。proof绑定工作和输出摘要、任务ID、租约、时间，原样重试不重复写版本。发现/快照/加工回执属于本地企业配置，不是外部登记或第三方证明。
v0.3 企业治理与角色
每个登录/GET /me 响应的 actor 包含只读 permissions 数组，按当前人员角色派生。服务端再次执行权限和企业/对象范围检查，不能通过修改前端字段获得权限。operator、admin、steward、reviewer、consumer、auditor 为固定角色，具体能力可读 /roles。平台运营权限不自动授予其他企业私有数据访问。
| 方法与路径 | 权限和内容 |
|---|---|
GET /roles | 已登录；固定角色、名称、权限列表 |
GET /users | users.manage；仅本企业，不返回密码哈希或私钥 |
POST /users | users.manage；name,email,password,role；不能授予operator |
POST /users/{id}/access | users.manage；role,disabled；不能跨企业、自锁或移除最后管理员；实际变更撤销会话/未用签署挑战 |
GET /product-reviews | 产品准备/审核或审计权限；仅本企业审核历史、固定版本、创建人/申请人、字段和说明 |
POST /products/{id}/reviews | products.write；产品状态draft/unpublished/rejected；固定当前版本，进入pending_review |
POST /product-reviews/{id}/decision | products.review；approve,reason；创建人/申请人不能自审，意见必填；同一申请只处理一次 |
GET /space-governance | 已登录；已加入/持有的空间及允许查看的加入申请，包括历史归档状态 |
POST /spaces/{id}/requests | members.manage；reason；本企业申请加入，已有成员或已有待审申请拒绝 |
POST /membership-requests/{id}/decision | members.manage且为空间运营企业；approve,reason |
POST /spaces/{id}/profile | spaces.manage且为空间运营企业；name,description；仅活动空间 |
POST /spaces/{id}/leave | spaces.manage且为成员企业；存在未结束有效合约时409；空间运营企业不能退出自身空间 |
POST /spaces/{id}/archive | spaces.manage且为空间运营企业；存在未结束有效合约时409；保留历史证据 |
GET /policy-templates | contracts.read；仅本企业模板 |
POST /policy-templates | templates.write；name,description,durationHours,policy；durationHours为1至8760 |
POST /policy-templates/{id}/revision | templates.write；上述内容及当前version；并发修改时409；保留历史文档 |
POST /policy-templates/{id}/apply | contracts.write；version；必须当前有效版本，返回按当前时间计算的Policy，不会创建或签署合约 |
模板应用接口不接收产品编号；门户将返回参数复制到草稿并检查字段，创建合约时服务端仍校验产品字段、操作和策略。模板修订不会改写历史合约，也没有将模板库变成任意脚本执行入口。
新建数据集产品的 /status 不能直接发布；必须走审核申请/决定。待审产品也不能通过普通状态入口下架而留下悬空申请，须先作审核决定。既有内部CSV初始化路径保留兼容，不由HTTP新建产品入口开放。
读取内部目录要求assets.read；发现/快照/加工/取消要求assets.write。创建产品要求products.write，发布审核/下架要求products.review。拟定/修订合约要求contracts.write，签署/终止要求contracts.sign；使用人员可拟定，签署须由其企业管理员或审核员执行。任务提交/取消与审核、导出分别授权。auditor的任务列表不含结果明文。
GET /evidence：audit.read可取本企业管理日志及本企业参与合约；使用人员仅有evidence.contract，可取本企业参与的合约证据，不能读取party范围管理日志。证据不包含原始数据或聚合结果明文。
人员停用/改权不抹除已签历史合约；新请求使用当前权限，旧会话会401。空间退出/归档后，新签署、任务准入/续租/结果提交及使用方在线访问检查空间成员关系；历史证据仍可授权读取。当前无SSO、自定义角色、资源级ACL、在线密钥恢复或权威身份注销。
补充角色读取边界：没有assets.read的人员，即使与产品属于同一企业，产品响应也隐藏sourceRef/datasetVersionId。提供方仅具备jobs.review的人员可在交付前读取结果；使用方仍须结果获准且合约/空间有效。只读审计员始终不返回结果明文。
v0.4 生命周期接口
统一使用现有会话、CSRF、角色与企业隔离。版本修改携带当前 version；过期版本返回409 stale_version。历史仅本企业有 assets.read 的人员可查，写入分别要求 assets.write / products.write。
| 方法与路径 | 请求/结果 |
|---|---|
| GET /api/sources/:id/impact | 当前定义、版本历史、资产/传递数据集/当前产品数量、未完成采集数 |
| POST /api/sources/:id/revisions | {version,name,description,classification,status}；status为active/retired，返回新定义 |
| GET /api/assets/:id/versions | 当前资产、版本历史、直接快照和直接产品计数；完整加工依赖看来源impact |
| POST /api/assets/:id/revisions | {version,name,status}；人工别名和启停，字段及引用不可手工修改 |
| GET /api/products/:id/versions | 固定产品快照列表，版本倒序 |
| POST /api/products/:id/revisions | {version,name,description,datasetVersionId}；生成新草稿并使待审申请superseded；published先下架 |
| GET /api/pipelines/:id/versions | 不可变历史规则、输入版本 |
| POST /api/pipelines/:id/revisions | {version,name,inputs,plan}；输入1至2个质量通过版本，同连接器，原执行连接器不可替换 |
| GET /api/contracts/:id/releases | 双方有contracts.read的账号可查询解除历史 |
| POST /api/contracts/:id/releases | {reason}；生效合约一方有contracts.sign者发起，每合约最多一个pending |
| POST /api/contracts/:id/releases/:releaseId/decision | {approve,reason}；另一企业有contracts.sign者处理；拒绝保留合约，批准原子终止 |
| POST /api/contracts/:id/terminate | 保留紧急单方终止；审计mode=emergency，协商终止mode=bilateral |
数据源和资产有排队/执行中的采集时返回409 source_busy；先等待完成或取消。停用阻止新发现/快照，已有不可变快照仍允许加工与履约。重新发现不会启用已停用资产或覆盖人工别名。定义不物理删除历史文件。加工任务按规则版本去重，旧运行不会被新规则替换。
解除的409 release_pending/already_reviewed和403 counterparty_required是业务守卫；理由必填。平台账号确认与审计记录不能表述为本轮新增了CA电子签章。新流程共享原有租约、额度与结果访问撤销事务。
v0.5 可选EVM存证接口
统一要求会话、写请求CSRF与企业隔离。chain.manage仅operator/admin；chain.read另允许reviewer/auditor，后者看不到RPC地址、签名引用或签名器选择项。配置私钥仅由运维文件加载。
| 方法与路径 | 内容与约束 |
|---|---|
| GET /api/blockchain | 本企业连接、最近200条操作、固定模板摘要、自动检查点待处理数；管理员另获运维白名单和本企业签名引用 |
| POST /api/blockchain/nodes | name,rpcURL,chainId,genesisHash?,signerRef,confirmations,maxGasPrice,autoAnchor；真实核对链身份并固定创世块；同企业/链/账户仅一个活动连接 |
| POST /api/blockchain/nodes/:id/disable | 停止新提交与自动检查点，保留已签交易及原链回执核对；不撤销已签交易 |
| POST /api/blockchain/nodes/:id/deploy | 固定模板部署；持久化后由队列广播，同一连接部署幂等 |
| POST /api/blockchain/nodes/:id/anchors | kind,objectId,revision；六类固定版本/检查点；相同对象版本返回原交易 |
| POST /api/blockchain/operations/:id/retry | 仅管理员；重查并在必要时重播原交易；不生成替换nonce，不允许重播改变已回滚结果 |
| GET /api/blockchain/operations/:id/proof | 授权导出正文、随机盐及签名绑定；不包含RPC、私钥或原始签名交易；导出不等于当前验证通过 |
| POST /api/blockchain/operations/:id/verify | 当前RPC在线核验；成功明确scope=configured_rpc_and_platform_key、independentThirdParty=false；失败409 |
kind为dataset_version/product_version/asset_version/source_version/contract_version/audit_checkpoint。数据集对象ID是固定数据集版本ID；其他元数据版本指定正整数revision。数字合约和检查点revision=0分别使用当前合约版本/审计头，返回中固定实际版本。检查点objectId为本企业party:企业ID，或有权访问的contract:合约ID。
节点身份、可用性、部署模板、回执和承诺的失败均不会返回“已核验”。预备交易加密保存且不出现在API响应。客户端不接受任意Solidity、部署字节码、rawTx、私钥或自定义链执行脚本。在线证明核验使用服务器当前固定公钥与连接身份；独立CLI必须额外显式固定信任参数。完整事件链证据格式和原校验器保持独立。