Operation details
GET /v1/admin/gateways
List standalone Agent Gateways (platform session, system.gateway.manage)
- operationId
listAgentGateways- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
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.
Responses
listAgentGateways Responses| Status | Description |
|---|
200 | Gateways that are not deleted. Fields：items: array<AgentGateway> installation_id: string(uuid) standalone_access_open: boolean |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
↑ Back to list
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- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Request body
application/json · Required：Yes
createAgentGateway Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
host | string | Yes | Public Gateway name (domain or IP) |
|---|
Responses
createAgentGateway Responses| Status | Description |
|---|
201 | Created; binding_token is shown once. Fields：gateway: AgentGateway binding_token: string token_expires_at: string(date-time) |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | gateway_name_taken |
|---|
422 | invalid_input |
|---|
What to do on failure
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
DELETE /v1/admin/gateways/{id}
Delete a Gateway; every certificate it was issued is revoked
- operationId
deleteAgentGateway- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
deleteAgentGateway Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
deleteAgentGateway Responses| Status | Description |
|---|
204 | Deleted. |
|---|
404 | gateway_not_found |
|---|
What to do on failure
404 The resource does not exist or belongs to another tenant.
↑ Back to list
PUT /v1/admin/gateways/{id}/allowed-ips
Replace the addresses a bound Gateway may connect from (IPv4/IPv6, 1–16, audited)
- operationId
setAgentGatewayAllowedIPs- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
setAgentGatewayAllowedIPs Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
setAgentGatewayAllowedIPs Request body| Name | Type | Required | Description |
|---|
allowed_ips | array<string> | Yes | — |
|---|
Responses
setAgentGatewayAllowedIPs Responses| Status | Description |
|---|
200 | Saved (normalized). Fields：allowed_ips: array<string> |
|---|
404 | gateway_not_found |
|---|
409 | gateway_state_conflict (not bound yet) |
|---|
422 | invalid_input |
|---|
What to do on failure
404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
POST /v1/admin/gateways/{id}/binding-token
Replace the binding token of a pending Gateway (the previous token stops working)
- operationId
reissueAgentGatewayBindingToken- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
reissueAgentGatewayBindingToken Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
reissueAgentGatewayBindingToken Responses| Status | Description |
|---|
200 | New token. Fields：gateway: AgentGateway binding_token: string token_expires_at: string(date-time) |
|---|
404 | gateway_not_found |
|---|
409 | gateway_state_conflict (already bound) |
|---|
What to do on failure
404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
POST /v1/admin/gateways/{id}/disable
Disable a bound Gateway; its ControlInternal calls are refused
- operationId
disableAgentGateway- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
disableAgentGateway Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
disableAgentGateway Responses| Status | Description |
|---|
204 | Disabled. |
|---|
404 | gateway_not_found |
|---|
409 | gateway_state_conflict |
|---|
What to do on failure
404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
POST /v1/admin/gateways/{id}/enable
Re-enable a disabled Gateway
- operationId
enableAgentGateway- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
enableAgentGateway Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
enableAgentGateway Responses| Status | Description |
|---|
204 | Enabled. |
|---|
404 | gateway_not_found |
|---|
409 | gateway_state_conflict |
|---|
What to do on failure
404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list