cdnca

开放接口

/v1/admin/gateways

7 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/admin/gatewaysList standalone Agent Gateways (platform session, system.gateway.manage)登录会话
POST/v1/admin/gatewaysAdd a Gateway and issue its one-time binding token (1 hour, single use, only the SHA-256 is stored)登录会话
DELETE/v1/admin/gateways/{id}Delete a Gateway; every certificate it was issued is revoked登录会话
PUT/v1/admin/gateways/{id}/allowed-ipsReplace the addresses a bound Gateway may connect from (IPv4/IPv6, 1–16, audited)登录会话
POST/v1/admin/gateways/{id}/binding-tokenReplace the binding token of a pending Gateway (the previous token stops working)登录会话
POST/v1/admin/gateways/{id}/disableDisable a bound Gateway; its ControlInternal calls are refused登录会话
POST/v1/admin/gateways/{id}/enableRe-enable a disabled Gateway登录会话

契约文件：api/openapi/v1/control.yaml

接口详情

GET /v1/admin/gateways

List standalone Agent Gateways (platform session, system.gateway.manage)

operationId
listAgentGateways
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

The co-located Gateway of an all-mode installation is not listed. standalone_access_open is false until the control plane opens ControlInternal/Redis/NATS to Gateways; binding is refused until then.

响应

listAgentGateways 响应
状态码说明
200Gateways that are not deleted.

字段：items: array<AgentGateway> installation_id: string(uuid) standalone_access_open: boolean

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST /v1/admin/gateways

Add a Gateway and issue its one-time binding token (1 hour, single use, only the SHA-256 is stored)

operationId
createAgentGateway
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

请求体

application/json · 必填：是

createAgentGateway 请求体
名称类型必填说明
namestring是—
hoststring是Public Gateway name (domain or IP)

响应

createAgentGateway 响应
状态码说明
201Created; binding_token is shown once.

字段：gateway: AgentGateway binding_token: string token_expires_at: string(date-time)

401认证失败或会话已失效。
403当前身份没有执行该操作的权限。
409gateway_name_taken
422invalid_input

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

DELETE /v1/admin/gateways/{id}

Delete a Gateway; every certificate it was issued is revoked

operationId
deleteAgentGateway
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

deleteAgentGateway 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

deleteAgentGateway 响应
状态码说明
204Deleted.
404gateway_not_found

失败时怎么办

  • 404 资源不存在或不属于当前租户。

↑ 回到列表

PUT /v1/admin/gateways/{id}/allowed-ips

Replace the addresses a bound Gateway may connect from (IPv4/IPv6, 1–16, audited)

operationId
setAgentGatewayAllowedIPs
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

setAgentGatewayAllowedIPs 参数
名称位置类型必填说明
idpathstring(uuid)是—

请求体

application/json · 必填：是

setAgentGatewayAllowedIPs 请求体
名称类型必填说明
allowed_ipsarray<string>是—

响应

setAgentGatewayAllowedIPs 响应
状态码说明
200Saved (normalized).

字段：allowed_ips: array<string>

404gateway_not_found
409gateway_state_conflict (not bound yet)
422invalid_input

失败时怎么办

  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST /v1/admin/gateways/{id}/binding-token

Replace the binding token of a pending Gateway (the previous token stops working)

operationId
reissueAgentGatewayBindingToken
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

reissueAgentGatewayBindingToken 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

reissueAgentGatewayBindingToken 响应
状态码说明
200New token.

字段：gateway: AgentGateway binding_token: string token_expires_at: string(date-time)

404gateway_not_found
409gateway_state_conflict (already bound)

失败时怎么办

  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST /v1/admin/gateways/{id}/disable

Disable a bound Gateway; its ControlInternal calls are refused

operationId
disableAgentGateway
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

disableAgentGateway 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

disableAgentGateway 响应
状态码说明
204Disabled.
404gateway_not_found
409gateway_state_conflict

失败时怎么办

  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST /v1/admin/gateways/{id}/enable

Re-enable a disabled Gateway

operationId
enableAgentGateway
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

enableAgentGateway 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

enableAgentGateway 响应
状态码说明
204Enabled.
404gateway_not_found
409gateway_state_conflict

失败时怎么办

  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表