From 3cb12775b30d49adcbc37cd410b0bafa9e703e87 Mon Sep 17 00:00:00 2001 From: alick-liming Date: Tue, 27 Oct 2026 14:43:13 +0800 Subject: [PATCH] docs: align integration catalog permissions --- README.md | 2 +- README_zh.md | 2 +- openapi/openapi.en.json | 8 ++++---- openapi/openapi.zh.json | 8 ++++---- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6e5c6b6..92303c9 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ client, err := flashduty.NewClientWithAccessToken(accessToken) ## Public and dedicated integrations -Use `client.Integrations` for public integrations managed in the integration center. They can be connected to channels through subscriptions or routing and require integration permissions. Use `client.DedicatedIntegrations` for integrations owned by one channel; they require channel permissions, including access to that specific channel, rather than integration-center permissions. +Use `client.Integrations` for public integrations managed in the integration center. They can be connected to channels through subscriptions or routing and require integration permissions. Use `client.DedicatedIntegrations` for integrations owned by one channel; reads accept Channels Read, Channels Manage, or Integrations Read and require visibility of the owning channel; writes require Channels Manage and management access to that channel. The shared type catalog accepts these three read permissions; scoped App Keys must allow `integration.api:read:typeList` to query it. ```go req := &flashduty.ChannelIntegrationListRequest{ChannelID: 20001} diff --git a/README_zh.md b/README_zh.md index 270aa60..9d83845 100644 --- a/README_zh.md +++ b/README_zh.md @@ -66,7 +66,7 @@ client, err := flashduty.NewClientWithAccessToken(accessToken) ## 公共集成与专属集成 -集成中心管理的公共集成使用 `client.Integrations`，可通过订阅或路由接入协作空间，需要集成中心权限。属于某个协作空间的专属集成使用 `client.DedicatedIntegrations`，需要协作空间权限以及对目标空间的访问或管理权限，不需要集成中心权限。 +集成中心管理的公共集成使用 `client.Integrations`，可通过订阅或路由接入协作空间，需要集成中心权限。属于某个协作空间的专属集成使用 `client.DedicatedIntegrations`，读取允许协作空间查看、协作空间管理或集成中心查看权限，同时要求目标空间可见；写入须有协作空间管理权限以及目标空间的管理资格。共用的类型目录也允许这三项读取权限；限制了接口范围的 App Key 须允许 `integration.api:read:typeList` 才能查询。 ```go req := &flashduty.ChannelIntegrationListRequest{ChannelID: 20001} diff --git a/openapi/openapi.en.json b/openapi/openapi.en.json index 59ab2e5..3029bdd 100644 --- a/openapi/openapi.en.json +++ b/openapi/openapi.en.json @@ -67923,7 +67923,7 @@ "On-call/Integrations" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Public and dedicated integrations share this type catalog; it returns no configured integration instances, settings, or keys.\n- The App Key's `api_scopes` must allow `integration.api:read:typeList`; `channel.integration` scopes do not include this endpoint.\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.", "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list", "metadata": { "sidebarTitle": "List integration types" @@ -69115,7 +69115,7 @@ "On-call/Dedicated integrations" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- `channel_id` is required; `p` defaults to `1` and `limit` defaults to `100`, with a maximum of `100`.\n- `plugin_type` and `status` each accept one value.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- `channel_id` is required; `p` defaults to `1` and `limit` defaults to `100`, with a maximum of `100`.\n- `plugin_type` and `status` each accept one value.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-read-list", "metadata": { "sidebarTitle": "List dedicated integrations" @@ -69214,7 +69214,7 @@ "On-call/Dedicated integrations" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read**, **Channels Manage**, or **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- Private channels also require the account owner, an Admin, the channel creator, or membership in its owning or managing teams; public channels still require the API permission above.\n- The complete `integration_key` is returned; saved secret values in `settings` are returned as `******`. The integration key authenticates alert ingestion and is separate from the management App Key.", "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-read-info", "metadata": { "sidebarTitle": "Get dedicated integration detail" @@ -69304,7 +69304,7 @@ "On-call/Dedicated integrations" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- The channel must be enabled; the integration type must be enabled, belong to `event.alert`, and be supported by your subscription.\n- If you know the `plugin_type`, create the integration directly without querying types first. You can optionally query `POST /integration/type/list` for supported alert types if you have **Integrations Read** permission.\n- An omitted `name` uses the integration type default; an omitted `integration_key` is generated. A supplied key must have 35 characters, match the account suffix, and not be used by another integration.\n- Success returns `integration_id` and `integration_key`; use that `integration_id` for subsequent operations.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- These APIs manage channel-owned dedicated integrations; use `/integration/*` for public integrations.\n- The App Key's `api_scopes` must allow the operation; permissions follow the user who owns the key.\n- You also need management access to the target channel: the account owner, an Admin, the channel creator, or a managing-team member. The owning team applies when no managing team is set.\n- Creating the integration does not independently grant channel management access; Integrations Manage does not grant access to this endpoint.\n- The channel must be enabled; the integration type must be enabled, belong to `event.alert`, and be supported by your subscription.\n- If you know the `plugin_type`, create the integration directly without querying types first. You can optionally query `POST /integration/type/list` for alert types with Channels Read, Channels Manage, or Integrations Read; the App Key's `api_scopes` must also allow `integration.api:read:typeList`.\n- An omitted `name` uses the integration type default; an omitted `integration_key` is generated. A supplied key must have 35 characters, match the account suffix, and not be used by another integration.\n- Success returns `integration_id` and `integration_key`; use that `integration_id` for subsequent operations.\n- Every call is recorded in the account audit log.\n- Concurrent changes to integrations in the same channel return `RequestLocked`; retry after the current change completes.", "href": "/en/api-reference/on-call/dedicated-integrations/channel-integration-write-create", "metadata": { "sidebarTitle": "Create dedicated integration" diff --git a/openapi/openapi.zh.json b/openapi/openapi.zh.json index b74efe9..b4a0c1d 100644 --- a/openapi/openapi.zh.json +++ b/openapi/openapi.zh.json @@ -67923,7 +67923,7 @@ "On-call/集成中心" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 公共集成和专属集成共用此类型目录，不返回已配置的集成实例、配置或 Key。\n- App Key 的 `api_scopes` 须允许 `integration.api:read:typeList`；`channel.integration` 范围不包含此接口。\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。", "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list", "metadata": { "sidebarTitle": "查询集成类型列表" @@ -69115,7 +69115,7 @@ "On-call/专属集成" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- `channel_id` 必填；`p` 默认 `1`，`limit` 默认 `100`，最多 `100`。\n- `plugin_type` 和 `status` 各接受单个值。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- `channel_id` 必填；`p` 默认 `1`，`limit` 默认 `100`，最多 `100`。\n- `plugin_type` 和 `status` 各接受单个值。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-list", "metadata": { "sidebarTitle": "查询专属集成列表" @@ -69214,7 +69214,7 @@ "On-call/专属集成" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**、**协作空间管理** 或 **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 查看私有空间还要求您是账户所有者、Admin、空间创建者，或所属团队、管理团队的成员；公开空间仍需上述接口权限。\n- 返回完整 `integration_key`；`settings` 中已保存的密钥类值返回 `******`。集成 Key 用于告警接入，与管理接口的 App Key 不同。", "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-read-info", "metadata": { "sidebarTitle": "查看专属集成详情" @@ -69304,7 +69304,7 @@ "On-call/专属集成" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 目标空间必须已启用；集成类型须已启用、属于 `event.alert`，且您的订阅支持该类型。\n- 已知 `plugin_type` 时可直接创建，无需先查询类型。拥有**集成中心查看**权限时，可选用 `POST /integration/type/list` 查询支持的告警类型。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 这些接口管理协作空间专属集成；公共集成使用 `/integration/*`。\n- App Key 的接口授权范围（`api_scopes`）须允许本次操作；权限按 App Key 所属用户判断。\n- 您还须拥有目标空间的管理权限：账户所有者、Admin、空间创建者，或管理团队成员。未设置管理团队时，按所属团队判断。\n- 创建过这条集成不单独授予空间管理权限；集成中心管理权限也不授予本接口访问权。\n- 目标空间必须已启用；集成类型须已启用、属于 `event.alert`，且您的订阅支持该类型。\n- 已知 `plugin_type` 时可直接创建，无需先查询类型。也可选用 `POST /integration/type/list` 查询告警类型；该接口支持协作空间查看、管理或集成中心查看权限，App Key 的 `api_scopes` 还须允许 `integration.api:read:typeList`。\n- 省略 `name` 时使用集成类型的默认名称；省略 `integration_key` 时自动生成。自带 Key 须为 35 个字符、匹配账户后缀，且未被其他集成使用。\n- 成功后返回 `integration_id` 和 `integration_key`；后续操作使用返回的 `integration_id`。\n- 每次调用均记录到账户审计日志。\n- 同一空间的集成正在变更时返回 `RequestLocked`，请稍后重试。", "href": "/zh/api-reference/on-call/dedicated-integrations/channel-integration-write-create", "metadata": { "sidebarTitle": "创建专属集成"