Create Environment

POST /environments

Create Environment

Create an environment in the authenticated organization. Environment names are case-sensitive and must be unique within the organization.

Parameters

Request body

Content type: application/json

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

Responses

• 201: Created

• 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 POST /environments, response 400 above.

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

• 409: Request conflicts with current resource state. Response fields (application/json): identical to POST /environments, response 400 above.

cURL

curl -X POST '$AISIX_CP/environments' -H 'Authorization: Bearer $AISIX_TOKEN'