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

> Learn to configure enterprise API gateways in Flue. Easily set custom base URLs and authentication headers using registerProvider and configureProvider for robust API management.

- Repository: [Astro/flue](https://github.com/withastro/flue)
- Tags: how-to-guide
- Published: 2026-05-11

---

**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`](https://github.com/withastro/flue/blob/main/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`](https://github.com/withastro/flue/blob/main/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:

```typescript
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`](https://github.com/withastro/flue/blob/main/runtime/providers.ts), this stores a `ProviderSettings` object in the `providerOverrides` map, allowing you to rotate tokens or switch gateways dynamically.

```typescript
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`](https://github.com/withastro/flue/blob/main/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`](https://github.com/withastro/flue/blob/main/examples/hello-world/.flue/app.ts)) to route all Anthropic traffic through your corporate gateway:

```typescript
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`](https://github.com/withastro/flue/blob/main/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`](https://github.com/withastro/flue/blob/main/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`](https://github.com/withastro/flue/blob/main/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.