API7 Docs
AISIX AI GatewayAISIX Cloud Admin APIUpdate Environment

Update Environment

PATCH /environments/{env_id}

PATCH /environments/{env_id}

Interactive request editor loads with JavaScript.

Authorization

BearerAdminToken
AuthorizationBearer <token>

Organization-scoped admin token. Read operations require a valid token, and write operations require a token with write permission.

In: header

Path Parameters

env_id*string

Environment ID that scopes the request.

Formatuuid

Request Body

application/json

Fields that can be updated on an environment. Every field is optional; omitting one leaves its current value alone.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "$AISIX_CP/environments/$ENV_ID" \  -H "Authorization: Bearer $AISIX_TOKEN" \  -H "Content-Type: application/json" \  -d '{}'

OK

{
  "environment": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
    "display_name": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "mcp_resource_url": "string",
    "mcp_anonymous": {
      "enabled": true,
      "api_key_id": "b0dd218e-3bcf-4bdb-a1e3-0689d60a8afd",
      "source_cidrs": [
        "string"
      ],
      "servers": [
        "string"
      ],
      "aggregate_entry": false
    }
  }
}
Complete operation details and schema variants

PATCH /environments/{env_id}

Update Environment

Update an environment's display name and MCP OAuth discovery settings. Fields that are omitted keep their current value.

Parameters

  • env_id (path, string, required): Environment ID that scopes the request.

Request body

Content type: application/json

  • display_name (string, optional): Human-readable environment name, unique within the organization. Renaming is a control-plane label change only: gateways identify their environment by ID, so a rename never touches running data planes or the configuration they serve.

  • mcp_resource_url (string, optional): Canonical public URL of this environment's MCP endpoint, for example https://gateway.example.com/mcp. Setting it — together with at least one enabled OIDC provider — turns on OAuth discovery for MCP clients: the gateway publishes protected resource metadata and points unauthenticated callers at it, so standard MCP clients can sign in through the configured identity provider instead of presenting a pre-issued API key. Must be an absolute http or https URL whose path is exactly /mcp, with no query or fragment, and access tokens must carry this URL in their audience claim. Set to null to clear the value and turn OAuth discovery off.

  • mcp_anonymous (object, optional): Anonymous access to this environment's MCP entries. Omit to leave the current settings untouched; set to null to turn anonymous access off, so every /mcp request needs a valid gateway credential again.

This and mcp_resource_url are independent and share one projected configuration row, so updating either leaves the other as it was.

  • allOf variant 1

  • mcp_anonymous.enabled (boolean, optional): Whether anonymous access is served. Set to false to close it while keeping the principal and allowlists configured.

  • mcp_anonymous.api_key_id (string, required): The API key anonymous traffic runs as. Must belong to this environment, and must carry its own mcp_access block: a key without one takes its tools from the environment and team layers alone, so a later change to those would silently widen what anonymous callers can reach. The key's own allow list bounds it whatever the other layers do.

  • mcp_anonymous.source_cidrs (array, required): Client source CIDRs allowed to enter anonymously. Required and non-empty: with no credential to check, network reachability is the only gate in front of the principal. Matched against the source address the gateway's real-IP chain resolves, never a caller-supplied header. Use 10.0.0.1/32 for a single address.

  • mcp_anonymous.servers (array, required): Registered MCP server names anonymous callers may reach, each served at /mcp/{server}. Every name must be an approved server exposed to this environment.

This list is the principal's CEILING, not merely the set of scoped entries: anonymous callers reach the tools of these servers and no others, on the aggregated /mcp endpoint as much as the scoped ones. Without that, a principal whose own grant is wider than the list could name <server>__<tool> on the aggregated endpoint and reach a server whose scoped entry is closed.

Required and non-empty: an empty ceiling admits no tool on either entry, so it could never serve a useful request. It is also why a newly registered MCP server is never anonymous by default — reaching anonymous callers is always a name added here.

  • mcp_anonymous.aggregate_entry (boolean, optional): Whether the aggregated /mcp endpoint ALSO serves anonymous callers. It exposes the same servers, under their <server>__<tool> namespaced names.

Off by default: it is the entry a standard MCP client uses for OAuth discovery, and serving it anonymously suppresses the 401 that carries the discovery hint, so such clients silently stay on the anonymous grant instead of signing in. The namespaced names are also not what a client migrating from a single-server endpoint uses.

Responses

  • 200: OK

  • environment (object, required): Environment view used in list, create, and get responses.

  • environment.id (string, required): Environment ID.

  • environment.org_id (string, required): Organization ID that owns this environment.

  • environment.display_name (string, required): Human-readable environment name.

  • environment.created_at (string, required): Time when the environment was created.

  • environment.updated_at (string, required): Time when the environment was last updated.

  • environment.mcp_resource_url (string, optional): Canonical public URL of this environment's MCP endpoint. Absent when OAuth discovery for MCP clients is not configured.

  • environment.mcp_anonymous (object, optional): Anonymous access settings for this environment's MCP entries. Absent when every /mcp request needs a valid gateway credential (the default).

  • allOf variant 1

  • environment.mcp_anonymous.enabled (boolean, optional): Whether anonymous access is served. Set to false to close it while keeping the principal and allowlists configured.

  • environment.mcp_anonymous.api_key_id (string, required): The API key anonymous traffic runs as. Must belong to this environment, and must carry its own mcp_access block: a key without one takes its tools from the environment and team layers alone, so a later change to those would silently widen what anonymous callers can reach. The key's own allow list bounds it whatever the other layers do.

  • environment.mcp_anonymous.source_cidrs (array, required): Client source CIDRs allowed to enter anonymously. Required and non-empty: with no credential to check, network reachability is the only gate in front of the principal. Matched against the source address the gateway's real-IP chain resolves, never a caller-supplied header. Use 10.0.0.1/32 for a single address.

  • environment.mcp_anonymous.servers (array, required): Registered MCP server names anonymous callers may reach, each served at /mcp/{server}. Every name must be an approved server exposed to this environment.

This list is the principal's CEILING, not merely the set of scoped entries: anonymous callers reach the tools of these servers and no others, on the aggregated /mcp endpoint as much as the scoped ones. Without that, a principal whose own grant is wider than the list could name <server>__<tool> on the aggregated endpoint and reach a server whose scoped entry is closed.

Required and non-empty: an empty ceiling admits no tool on either entry, so it could never serve a useful request. It is also why a newly registered MCP server is never anonymous by default — reaching anonymous callers is always a name added here.

  • environment.mcp_anonymous.aggregate_entry (boolean, optional): Whether the aggregated /mcp endpoint ALSO serves anonymous callers. It exposes the same servers, under their <server>__<tool> namespaced names.

Off by default: it is the entry a standard MCP client uses for OAuth discovery, and serving it anonymously suppresses the 401 that carries the discovery hint, so such clients silently stay on the anonymous grant instead of signing in. The namespaced names are also not what a client migrating from a single-server endpoint uses.

  • 400: Request body or parameters failed validation.

  • error (object, required): Error details.

  • error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

  • error.message (string, required): Human-readable explanation; safe to surface to operators.

  • 401: Missing or invalid bearer. Response fields (application/json): identical to PATCH /environments/{env_id}, response 400 above.

  • 403: Authenticated request is not permitted. Response fields (application/json): identical to PATCH /environments/{env_id}, response 400 above.

  • 404: Resource not found. Response fields (application/json): identical to PATCH /environments/{env_id}, response 400 above.

cURL

curl -X PATCH '$AISIX_CP/environments/{env_id}' -H 'Authorization: Bearer $AISIX_TOKEN'

Get Environment by ID

Previous Page

Delete Environment

Next Page