Passthrough Routing

Passthrough is the default routing layer (L1). The gateway proxies your request straight to the upstream provider the request names, with no model remapping. It adds telemetry and security scanning along the way, and forwards the request body as you wrote it, so the request must be in the wire format the provider speaks — see Which SDK to call a provider with.

​

When passthrough applies

A request uses passthrough when it names a connected provider instead of a route. There are two ways to name one:

• The <provider-slug>::<model> prefix in the model field. The slug is the routing identifier you gave the provider when you connected it:
  { "model": "openai::gpt-4o", "messages": [{ "role": "user", "content": "Hello" }] }
  
• A bare model plus the x-to11-provider-id header, carrying the provider’s id. This is for a client that picks its own model string, such as a coding agent; to11 code sets it for you. The header is read only when the model has no prefix.

A bare model name with neither is rejected with 400 Bad Request — the gateway does not guess a provider from the model name, and a bare name never matches a route or function; those are called as route::<name> and function::<name>. See Naming the provider in a request. Naming the provider chooses where the request goes; it is not a way around that provider’s access policy. A model the provider does not serve in the request’s environment returns a 404, whichever form you used.

​

Choosing passthrough credentials

When you connect a provider in the Project → AI Gateway → Providers connect-provider drawer, you can choose a passthrough (BYOK) credential mode for it. In that mode no key is stored, and the caller’s own provider key is used to reach the upstream API. See Connecting a provider.

​

Which credential is used

A passthrough request can be served by a managed credential or by the caller’s own provider key. The precedence default is managed-credential-wins: if a stored credential resolves for the request, the gateway uses it. The caller’s own key — supplied in the Authorization header (or x-api-key for providers that use it) — is used when no managed credential resolves.

​

Coexistence with managed routing

Passthrough and managed routing live side by side in the same project, and the request decides which one applies: route::<name> and function::<name> use managed routing, while <provider-slug>::<model> and the x-to11-provider-id header use passthrough. You do not configure passthrough explicitly — every connected provider can be called this way. To confirm whether a given request went through passthrough or a managed route, open Projects → Traces in Observe. Passthrough requests are recorded with a passthrough routing path; managed requests record the resolved route, strategy, and target.

​

Next steps