Provider Passthrough

Provider passthrough lets an application call a provider-native endpoint through AISIX when the endpoint is not modeled as a first-class gateway route.

AISIX exposes ANY /passthrough/:provider/*rest for these requests. Passthrough keeps gateway authentication and upstream credential injection, but it performs less request and response handling than modeled proxy routes.

In this guide, you will send a provider passthrough request and review when this fallback path is appropriate.

Prerequisites

Before starting, prepare the following:

• A running AISIX gateway that can serve proxy requests.
• A caller API key allowed to access at least one model for the requested provider.
• A provider key with an api_base that can reach the provider-native endpoint, unless the provider has a built-in default base URL.

Send a Passthrough Request

Send passthrough traffic by naming the upstream provider in the path. The following example calls the upstream OpenAI models endpoint through AISIX:

curl -sS -X GET "http://127.0.0.1:3000/passthrough/openai/v1/models" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -o aisix-passthrough-models.json

AISIX authenticates the caller API key, selects an accessible model for the requested provider, injects that model's provider key as upstream authentication, strips unsafe headers, preserves the query string, and forwards the remaining path and body without endpoint-specific normalization.

The response is the upstream provider response, not a normalized AISIX model list:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model"
    }
  ]
}

Check that the response came back as an upstream list:

jq -r '.object' aisix-passthrough-models.json

The command should print:

list

Choose Passthrough Only When Needed

Passthrough is suitable for provider-specific APIs that are not exposed as first-class gateway routes, exploratory integration work, or temporary access while evaluating whether a native gateway endpoint is required.

Use a modeled proxy route instead when AISIX already supports the capability. Modeled routes resolve a caller-facing model alias and can apply route-specific behavior such as response normalization, output guardrails, token usage attribution, cache behavior, and endpoint-specific provider checks.

Passthrough Behavior

Passthrough keeps the provider-native request mostly intact:

• It accepts any HTTP method and preserves the query string and request body.
• It forwards safe request headers, and strips hop-by-hop headers and the provider key's configured strip_headers.
• It injects upstream authentication from the selected provider key.
• It relays the upstream status, response body, and safe response headers.

The provider path segment is used to find a configured model whose provider label matches that value and that the caller API key is allowed to access. This route is provider-scoped, not model-scoped. It does not choose a specific model alias the way a chat-completions request does. If multiple accessible models share the same provider but use different provider keys, avoid relying on implicit selection for production traffic.

Upstream authentication uses the provider's expected shape. Anthropic passthrough uses an API key header plus the Anthropic version header; most other built-in provider defaults use bearer authentication.

If the selected provider key does not set a base URL, AISIX uses a built-in default only for known providers such as OpenAI, Anthropic, Google, and DeepSeek. For other provider labels, configure the provider key base URL explicitly. When the base URL and passthrough path both include the same API-version segment, AISIX removes the duplicate segment before forwarding the request.

Passthrough Checks

When a passthrough request does not reach the expected upstream, first check the provider segment in the path, then check which configured model and provider key AISIX can select for that provider label. Passthrough does not take a model alias in the request body, so the selected provider key comes from an accessible model for that provider.

AISIX returns 403 when the caller API key is valid but cannot access any model for the requested provider. It returns 404 when no configured model matches the provider label. If AISIX reports that no default base URL is known, set the base URL on the selected provider key.

Next Steps

You have now seen how AISIX handles advanced proxy capabilities, from streaming and tool calling to provider-specific escape hatches. Next, continue with Operate AISIX to review deployment, security, observability, and troubleshooting.