Skip to navigation

Passthrough plugin

The Passthrough plugin lets a client call an LLM provider with its own credentials (“bring your own key”) through a route that has no connection. The client names the provider, the provider’s origin, and the path in X-Fabric-* request headers. The gateway checks them, calls that origin, and relays the answer. It removes every X-Fabric-* header before it forwards the request.

Where it runs

ProtocolsLLM routes with no connections
Scope kindsroute only
PhaseRequest

A passthrough call has no connection, so connection settings don’t apply: no timeout, retry, failover, or allowed models list. The plugin asks for one attempt. With signed credentials (AWS SigV4 or a Google token), the gateway can retry once against the same origin.

Nothing requires an authentication plugin on a passthrough route. Add Key Auth or JWT Auth so that anonymous callers can’t use the route.

Configuration

The plugin has no configuration, and an instance with any configuration is rejected. The client supplies everything in request headers:

HeaderDescription
X-Fabric-ProviderThe provider: vertex-ai@v1, azure-openai@v1, or aws-bedrock@v1. Any other <name>@v1 ID is treated as an API-key provider, with the key in X-Fabric-1P-Auth-Key and the origin in X-Fabric-Target-Origin.
X-Fabric-Target-OriginThe provider origin, as https://host. Required for Vertex AI and Azure OpenAI. Not allowed for Bedrock, whose origin comes from the region.
X-Fabric-Target-URIThe path to call, starting with /.
X-Fabric-Vertex-Region, X-Fabric-Vertex-Project-ID, X-Fabric-Vertex-AuthVertex AI region, project, and API key or token.
X-Fabric-Azure-AuthAzure OpenAI API key or token.
X-Fabric-AWS-RegionBedrock region. Required for Bedrock.
X-Fabric-AWS-Access-Key-ID, X-Fabric-AWS-Secret-Access-Key, X-Fabric-AWS-Session-Token, X-Fabric-AWS-Role-ARN, X-Fabric-AWS-External-ID, X-Fabric-AWS-Session-NameBedrock credentials.
X-Fabric-Proxy-AuthorizationAn API key for Vertex AI or Bedrock.

Vertex AI, Azure OpenAI, and Bedrock accept only POST requests. For API-key providers, the integration catalog decides the allowed methods. A missing or invalid header gets 400 with a plain-text reason. A missing credential gets 401 in the provider’s error format.

The console’s create-route form requires a connection, so you can’t create a route with no connections there. Create the route with the admin API.

Example

{
"name": "byok",
"plugin_id": "passthrough",
"scope": { "kind": "route", "name": "byok-route" }
}

Set up the plugin

Add a Passthrough instance to an LLM route so that callers can bring their own provider credentials.

Prerequisites

Before you begin, make sure you have the following:

  • An LLM route with no connections. The control plane rejects the instance on a route of another protocol, or on a route that has a connection.
  • An authentication plugin on the route, such as Key Auth. Without one, anonymous callers can use the route.
  • The callers’ own provider credentials. The gateway never fills them in from stored credentials.

Add the instance

To add a Passthrough instance, do the following:

  1. In the sidebar, select Plugins.
  2. On the All tab, find Provider Passthrough, and then select Use. The New plugin instance form opens. The plugin applies only to routes, so the form has no Apply to field.
  3. In the field labeled Routes, select the route. If you select more than one, Fabric creates one instance for each and the name field becomes Base name.
  4. In Instance name, enter a name, for example byok.
  5. Review Request header contract. It lists the headers that callers send for each provider. The plugin has no configuration, and Edit as JSON isn’t available.
  6. Make sure Enabled is selected, and then select Create instance.

Verify the plugin

To confirm the route, send a request with the provider headers. This example calls Azure OpenAI:

curl -i "BASE_URL/PATH" \
-H "fg-api-key: GATEWAY_KEY" \
-H "X-Fabric-Provider: azure-openai@v1" \
-H "X-Fabric-Target-Origin: https://RESOURCE.openai.azure.com" \
-H "X-Fabric-Target-URI: /openai/deployments/DEPLOYMENT/chat/completions?api-version=VERSION" \
-H "X-Fabric-Azure-Auth: AZURE_KEY" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Hello"}]}'

Expect the provider’s response, for example 200. In Traces, the request appears on the route. The gateway removes every X-Fabric-* header before it calls the provider.

Fix common problems

ResponseCauseFix
400 with a plain-text reasonA header is missing or invalid. For example, the provider, origin, or path header is missing, the method isn’t POST, or the origin isn’t https://host.Fix the header named in the reason. For Bedrock, send X-Fabric-AWS-Region and no origin.
401 in the provider’s error formatA credential header for the provider is missing.Send the credential header from Request header contract.
503 Service UnavailableThe provider and path aren’t in the LLM integration catalog, or the route has a connection.Check the origin and path, and use a route with no connections.
⌂ 换网址