List Passthrough Routes

GET /environments/{env_id}/passthrough_routes

List Passthrough Routes

Return every passthrough route in the environment. The response is not paginated.

Parameters

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

Responses

• 200: OK

• data (array, required): Every passthrough route in the environment.

• data[].id (string, required): Unique passthrough route ID.

• data[].env_id (string, required): Environment the route belongs to.

• data[].name (string, required): Route name, unique within the environment and fixed at creation. Referenced by API keys' allowed_routes patterns and recorded on usage events for attribution.

• data[].path_prefix (string, optional): Gateway path prefix this route serves (segment-boundary match: /copilot matches /copilot and /copilot/x, never /copilotx). The prefix is stripped before the remainder joins the target URL. Must not claim a reserved gateway namespace (/v1, /mcp, /a2a, /admin, /livez, /readyz, /metrics). At least one of path_prefix / hosts is required; when both are set a request must satisfy both.

• data[].hosts (array, optional): Inbound Host values this route serves — the forward-proxy entry, where a TLS-terminating device delivers plaintext traffic with its original Host. Matched case-insensitively, ignoring any :port suffix. A leading *. wildcard matches exactly one extra label and must keep at least two literal labels (*.githubcopilot.com is accepted; *.com and a bare * are rejected). Host-matched requests keep their full path unless path_prefix also matched.

• data[].target_url (string, optional): Explicit upstream base URL; the matched remainder path and query are appended (a trailing /v1 on the target and a leading v1/ on the remainder de-duplicate). Exactly one of target_url / preserve_host: true must be configured.

• data[].preserve_host (boolean, required): Derive the target from the matched inbound host (https://<host>), for forward-proxy routes fanning one route over several official hosts. Only accepted together with hosts — the allowlist is what bounds the derived target.

• data[].auth_mode (object, required): How the gateway authenticates callers of this route. header_key requires auth_header_name; anonymous requires anonymous_key_id and a non-empty source_cidrs.

• allOf variant 1

• data[].auth_header_name (string, optional): Lowercase header carrying the gateway credential when auth_mode is header_key (for example x-aisix-api-key); stripped before forwarding. Rejected on any other auth_mode — the gateway never consults it there. Credential-bearing names (authorization, proxy-authorization, cookie, set-cookie, x-api-key) are rejected.

• data[].anonymous_key_id (string, optional): The environment API key this route's traffic runs as when auth_mode is anonymous. Its allowed_routes grant, rate limits, budget, and usage attribution apply unchanged, so anonymous traffic keeps a stable, governable principal. Rejected on any other auth_mode — the gateway never consults it there.

• data[].source_cidrs (array, optional): Client source CIDRs allowed to use this route. Required (non-empty) when auth_mode is anonymous; optional hardening for the other modes. Unset means no route-level source restriction.

• data[].credential_mode (object, required): How the upstream credential is produced. inject (the default) requires provider_key_id; forward_client forbids it.

• allOf variant 1

• data[].provider_key_id (string, optional): Provider key whose secret is injected upstream when credential_mode is inject; its header-strip list and TLS settings apply to the route's traffic. The provider key must be visible to this environment.

• data[].identity_header (string, optional): Optional lowercase header carrying the end-user identity injected by the upstream network device (for example x-aisix-user). Its value is recorded on usage events as client_identity for per-employee audit attribution and stripped before forwarding. Credential-bearing names are rejected.

• data[].timeout_ms (integer, optional): Upstream exchange bound in milliseconds. Bounds the response-header phase and any non-SSE body read, never a healthy SSE relay. When omitted, the gateway's default request timeout applies the same way.

• data[].enabled (boolean, required): Whether the route is active. A disabled route matches nothing.

• data[].created_at (string, required): Creation timestamp.

• data[].updated_at (string, required): Last update timestamp.

• 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 GET /environments/{env_id}/passthrough_routes, response 400 above.

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

cURL

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