How to Configure Enterprise API Gateways with Custom Base URLs and Authentication Headers in Flue

Use registerProvider() to declare gateway endpoints and static headers during app initialization, and configureProvider() to dynamically override base URLs or authentication tokens at runtime, with both APIs merging settings into the final model before request dispatch.

Flue, Astro's LLM SDK, routes AI calls through corporate proxies using a two-layer provider system defined in packages/sdk/src/runtime/providers.ts. When configuring enterprise API gateways with custom base URLs and authentication headers, you manipulate internal maps that feed into ProviderSettings, ensuring every model request carries your enterprise authentication requirements.

The Provider Architecture

Flue separates provider definitions from transport-level overrides through two distinct public APIs exported from @flue/sdk/app.

registerProvider: Static Gateway Declaration

The registerProvider(name, registration) function creates immutable entries in a module-scoped userModels map at packages/sdk/src/runtime/providers.ts (lines 90–94). This accepts an HttpProviderRegistration object containing the wire-protocol slug, target gateway URL, and static headers:

import { registerProvider } from '@flue/sdk/app';

registerProvider('corporate-anthropic', {
  api: 'anthropic-completions',
  baseUrl: 'https://gateway.mycorp.com/anthropic',
  apiKey: process.env.ANTHROPIC_GATEWAY_KEY,
  headers: {
    'x-company-id': 'acme-inc',
    'x-api-client': 'flue',
  },
});

configureProvider: Runtime Overrides

The configureProvider(providerSlug, settings) function patches existing providers without redefining their registration. Located at lines 61–66 of runtime/providers.ts, this stores a ProviderSettings object in the providerOverrides map, allowing you to rotate tokens or switch gateways dynamically.

import { configureProvider } from '@flue/sdk/app';

configureProvider('anthropic', {
  baseUrl: 'https://gateway.mycorp.com/anthropic',
  headers: {
    Authorization: `Bearer ${process.env.ENTERPRISE_ANTHROPIC_TOKEN}`,
    'x-request-id': crypto.randomUUID(),
  },
});

How Settings Merge at Request Time

Before any LLM call executes, Flue resolves the model through resolveModel in packages/sdk/src/internal.ts (lines 55–86). This function:

1. Retrieves the base model from userModels or built-in defaults.
2. Checks providerOverrides for the matching provider slug via getProviderConfiguration.
3. Applies overrides through applyProviderSettings (lines 11–15), where baseUrl replaces the default endpoint and headers shallow-merge with model-level defaults.

If both registerProvider and configureProvider define headers, the runtime configuration takes precedence for conflicting keys.

Complete Enterprise Setup Example

Combine both APIs in your application entry point (referenced in examples/hello-world/.flue/app.ts) to route all Anthropic traffic through your corporate gateway:

import { registerProvider, configureProvider, flue } from '@flue/sdk/app';
import { Hono } from 'hono';

// Step 1: Register the corporate gateway
registerProvider('my-anthropic', {
  api: 'anthropic-completions',
  baseUrl: 'https://gateway.mycorp.com/anthropic',
  apiKey: process.env.ANTHROPIC_GATEWAY_KEY,
  headers: { 'x-org-id': '12345' },
});

// Step 2: Conditionally override for specific environments
if (process.env.ENTERPRISE_ANTHROPIC_TOKEN) {
  configureProvider('anthropic', {
    baseUrl: 'https://gateway.mycorp.com/anthropic',
    headers: {
      Authorization: `Bearer ${process.env.ENTERPRISE_ANTHROPIC_TOKEN}`,
    },
  });
}

const app = new Hono();
app.route('/', flue());
export default app;

When agents call init({ model: 'anthropic/claude-haiku-4-5' }), Flue dispatches requests to your enterprise gateway with injected authentication headers.

Environment-Specific Behavior

On Node.js, the SDK automatically falls back to process.env for missing apiKey values in the registration. On Cloudflare Workers, the same ProviderSettings apply, though requests route through the Workers AI binding when the registration's api matches CLOUDFLARE_AI_BINDING_API.

Summary

• Use registerProvider in packages/sdk/src/runtime/providers.ts to declare enterprise gateway endpoints and static authentication headers during initialization.
• Use configureProvider to dynamically patch baseUrl or inject per-request headers (like rotating bearer tokens) without redeploying.
• Both APIs feed into ProviderSettings, which applyProviderSettings merges into the resolved model in packages/sdk/src/internal.ts before dispatch.
• Headers shallow-merge with existing model defaults, while baseUrl completely overrides the default endpoint.

Frequently Asked Questions

What's the difference between registerProvider and configureProvider?

registerProvider creates a new provider entry in the userModels map with a complete HttpProviderRegistration, including the wire-protocol identifier and default gateway URL. configureProvider only patches transport settings (baseUrl, headers, apiKey) for existing providers via the providerOverrides map, making it ideal for runtime configuration changes without touching registration code.

Can I rely on environment variables for API keys instead of hardcoding them?

Yes. While you can pass apiKey directly to registerProvider, Flue checks process.env for missing keys on Node.js. For runtime tokens, use configureProvider to inject Authorization headers from environment variables immediately before model instantiation.

How are headers merged when using both APIs?

applyProviderSettings in packages/sdk/src/internal.ts performs a shallow merge. Headers from configureProvider override conflicting keys from registerProvider, while non-conflicting keys from both sources persist. The merge happens after model resolution but before the HTTP request dispatches.

Does this configuration work with Cloudflare Workers?

Yes. The same ProviderSettings logic applies in Cloudflare Workers environments. However, if your registration's api field matches the internal CLOUDFLARE_AI_BINDING_API constant, Flue routes the request through the native Workers AI binding rather than your custom baseUrl, while still applying any custom headers you've configured.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}