跳到主要内容
Sursa Developers

POST/v1/apps/{app_id}/rotate-secret

轮换客户端密钥

rotate_app_secret

为 confidential 应用签发新的 client_secret，并只返回一次。旧的密钥立即失效；已签发的令牌继续有效。在 1.62.0 中新增。

身份验证

在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。

路径参数

  • app_idstring必填

    应用 ID（app_…），同时也是 client_id。

    length ≤ 36

请求头参数

  • Idempotency-Keystring

    写操作安全重试所用的键：1 到 255 个可打印 ASCII 字符；建议每个逻辑操作使用一个 UUID v4。24 小时内使用同一个键重试不会再次执行操作，而是返回已保存的响应（状态、响应头和正文），并附带 Idempotency-Replayed: true 头。同一个键配合不同的方法、路径、Content-Type 或正文时返回 409 api.idempotency_mismatch；第一个请求仍在执行时返回 409 api.idempotency_in_progress，并附带 Retry-After: 1。收到 5xx 或 429 响应后，该键被释放，重试会再次执行操作。键的作用范围是组织和调用方（API 密钥、用户或自定义数据源密钥）。

    length ≥ 1, length ≤ 255

响应

200成功响应

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

  • Idempotency-Replayed

    为 true 时表示该响应是按此 Idempotency-Key 从已保存的响应重放的：操作没有再次执行。

application/json

对象：OAuthAppWithSecret

  • idstring必填

    应用 ID（app_ 加 32 个十六进制字符），同时也是 client_id。

  • namestring必填

    员工在授权同意页面上看到的名称。

  • descriptionstring必填

    授权同意页面上的描述（可以为空）。

  • homepage_urlstring | null必填

    应用的网站。

  • client_typeOAuthClientType必填
  • redirect_urisarray of string必填

    允许的重定向 URI（按字符串精确匹配）。

  • scopesarray of OAuthScope必填

    应用可以申请的权限范围。

  • client_secret_prefixstring | null必填

    客户端密钥的前几个字符，用于识别；公开应用为 null。

  • rolestring | null必填

    客户端凭据令牌的角色（admin、editor、verifier、viewer）；公开应用为 null。

  • data_profilestring | null必填

    客户端凭据令牌的数据权限档案；公开应用为 null。

  • authorizationsinteger必填

    有效的员工授权数量。

  • created_atstring (date-time)必填
  • updated_atstring (date-time)必填
  • client_secretstring | null必填

    客户端密钥（kbcs_…），只显示一次；公开应用为 null。

401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

403不允许执行该操作：角色权限不足、无权访问合集或卡片、请求在“View as”模式下执行，或组织已被暂停或删除（`detail` 为对象，包含 `code: org_suspended | org_deleted`）。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

404对象不存在或您无权访问。对于访问受限的对象，API 不会确认其是否存在。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

409对象状态不允许执行该操作，例如存在重复、正在索引，或作业已处理过。

响应头

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。

响应头

  • Retry-After

    重试请求前需要等待的秒数。

  • RateLimit-Policy

    当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。

  • RateLimit

    RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。

  • X-RateLimit-Limit

    RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。

  • X-RateLimit-Remaining

    最严格限制下的剩余请求数。

  • X-RateLimit-Reset

    距最严格限制重置的秒数。

application/json

对象：Error

错误码

除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。

安全重试

每个 POST 和 PATCH 请求都传入 Idempotency-Key 头（例如一个 UUID）。24 小时内用同一个键重试时，返回已保存的响应，不会再次执行请求。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← apps · API 参考