Dureach

API 身份验证和快速开始

创建 API 密钥，发送经过身份验证的请求，并了解面向客户的 API 边界。

Dureach 通过带版本的 /api/ 路由提供客户 API 资源。应用还包含内部 /api/v1/ 和 /api/v2/ 路由。内部路由不自动属于公开 API；只能使用 API 参考 中列出的路径。

创建密钥

  1. 在应用中打开 Settings → Integrations。
  2. 打开 API 密钥区域，用所需的最低权限创建密钥。
  3. 为密钥设置清晰名称，只选择集成需要的 scopes，将密钥复制一次到服务器端密钥管理器，并在文档和示例中使用 YOUR_OAUTH_ACCESS_TOKEN。
  4. 如果密钥泄露，请撤销它并创建替代密钥；不要把密钥粘贴到浏览器 bundle、URL、截图、issue 或日志中。

身份验证

在 Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN 请求头中发送密钥。不要让密钥出现在浏览器 bundle、URL、截图、issue 或日志中。请求作用于创建该密钥的活动工作区。

curl --fail-with-body 'https://app.dureach.com/api/v2/webhooks?limit=25' \\
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \\
  -H 'Accept: application/json'

API 密钥和 webhook 管理资源位于 /oauth/service-accounts、/api/v2/webhooks 和 /api/v2/webhook-events。构建集成前，先检查工作区访问权限和套餐权限。

请求和响应格式

使用包含 name 和非空 scopes 数组的 JSON 请求体创建密钥。创建响应包含 id、name、scopes、key、workspace_id、timestamp_created 和 timestamp_updated。完整密钥只返回一次；之后读取时只显示安全前缀。

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read"]
}

列表响应使用 items 数组，也可能包含 next_starting_after。请求下一页时原样保留该游标。API 密钥和 webhook 列表端点默认返回 25 条记录；webhook 和 webhook-event 页面最多返回 100 条。webhook 记录包括 campaign、name、target_hook_url、event_type 和 custom_interest_value；webhook 事件记录包括投递状态和重试字段。

操作清单

  1. 使用文档规定的准确方法和路径；应用私有路由和 runner 路由不是客户 API 端点。
  2. 限制页面大小，并遵循端点提供的游标或分页字段。
  3. 将 401 视为身份验证无效或已撤销，将 403 视为权限或套餐权限失败。
  4. 只对临时服务器错误重试，并为写入使用有界 backoff 和幂等策略。不要盲目重试 400、401、403、404、409 或 429。
  5. 为支持保存请求 ID 和脱敏后的错误代码，不要保存密钥或私人 payload。

让 webhook consumer 保持幂等：在确认接收前保存事件标识符，在配置了签名时验证签名，并能够处理投递重试。

错误

API 密钥错误使用包含 statusCode、error 和 message 的 JSON；较新的端点还可能包含机器可读的 code。将 400 视为输入无效，401 视为身份验证失败，403 视为授权或套餐权限失败，404 视为未知资源，429 视为速率或用量限制。不要盲目重试 4xx 响应。

相关页面

请参阅 API webhooks 和使用限制。

身份验证失败表

HTTP 状态含义修复
400JSON、字段、游标或 limit 无效。验证请求并使用文档规定的枚举/值。
401bearer 密钥缺失、无效或已撤销。发送 Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN；替换已撤销的密钥。
403scope、角色、工作区或套餐不允许该操作。添加所需 scope，或请工作区管理员启用访问权限。
404资源或路径不存在。确认版本、UUID 和公开端点列表。
429速率或用量限制。遵循响应中的指引，并使用有界 backoff 重试。

安全验证

先执行只读请求，确认响应中的工作区和 items 结构，并按返回值原样保存 next_starting_after 游标。写入时只记录 HTTP 状态、脱敏错误代码和请求 ID。绝不要记录 bearer 密钥或 webhook payload。