Destinations

A destination is a named upstream the gateway can call. Routes reference destinations by name, so switching providers is a change to a route rather than to a caller.

destinations:
  openai-primary:
    kind: openai
    base_url: "https://api.openai.com"
    credentials:
      vault: openai-key
    model_map:
      "gpt-5": "gpt-4o"
    pricing:
      input_per_1m: 2.5
      output_per_1m: 10.0

Fields

Any other keys are passed through to the adapter, which is how provider-specific settings such as Azure's deployment and api_version are supplied.

Supported kinds

An unrecognized kind fails at boot with an error naming the destination and listing what is supported.

Native API-key destinations

Use native_api_key when a client needs a provider's native JSON or SSE protocol without translating it to Chat Completions. Declare the provider, protocol, trusted upstream URL, allowed paths, and the vault that holds its static key:

destinations:
  pi-openai:
    kind: native_api_key
    provider: openai
    api: openai-responses
    base_url: https://api.openai.com
    allowed_paths: [/v1/responses]
    auth: { type: bearer }
    credentials: { vault: openai-key }

routes:
  - name: llm-pi-openai-openai-responses
    match: { path: /v1/proxy/openai/openai-responses }
    strategy: { mode: fallback, targets: [{ destination: pi-openai }] }
    idempotency_safe: false

The proxy requires one matching destination and route. It rejects retries, multiple targets, fallback to another destination, target parameter shaping, and content guardrails. The allowed_paths list restricts upstream requests; an arbitrary path under /v1/proxy/ is not forwarded. Supported protocols include OpenAI Responses, Anthropic Messages, OpenAI Chat Completions, and Google GenerateContent. Configure allowed_paths and the upstream authentication headers for the provider protocol you select.

Credentials

Every destination needs credentials.vault, including MCP destinations. The gateway resolves the named vault resolver at call time and injects the result upstream. Model destinations can use credentials.credential_id to share one resolver while selecting different logical credentials. Static MCP requests select the credential with X-Orca-Credential-Id; dynamic MCP resolution returns the trusted credential id together with the endpoint. The credential is never returned to the caller and never appears in a response. See Vaults for the resolvers.

Model destinations

These examples show the provider-specific fields on model destinations. See Model providers for complete credential schemes and request examples.

destinations:
  anthropic-primary:
    kind: anthropic
    base_url: "https://api.anthropic.com"
    credentials:
      vault: anthropic-key

  azure-gpt4:
    kind: azure_openai
    base_url: "https://my-azure.openai.azure.com"
    credentials:
      vault: azure-key
    deployment: gpt-4o-prod
    api_version: "2024-08-01-preview"

  bedrock-claude:
    kind: bedrock
    region: us-west-2
    credentials:
      vault: aws-creds
    model_map:
      "claude-3-sonnet": "anthropic.claude-3-sonnet-20240229-v1:0"

  vertex-gemini:
    kind: vertex
    project: my-gcp-project
    location: us-central1
    credentials:
      vault: gcp-sa

Provider requirements

All model adapters require credentials.vault. Their remaining required fields differ:

model_map is what lets callers use one model name across providers. A caller asking for claude-3-sonnet gets the Bedrock model id when the request lands on bedrock-claude, without knowing that mapping exists.

pricing is a per-destination price override for spend calculation, calendar budgets, and usage records. Without it, the gateway uses plugins.cost_model when configured. With no cost model at all, request and token limits still work and dollar spend is unpriced. When a cost model is configured but cannot price a selected model, spend.admission.unpriced_model applies: deny (the default) rejects it, estimate reserves a configured flat amount, and allow_untracked admits it without dollar accounting.

See Pricing for the available price sources and Registry integration.

MCP destinations

An MCP destination proxies JSON-RPC tool calls rather than model calls. It takes base_url (or the legacy url alias) and a vault:

destinations:
  github:
    kind: mcp
    base_url: "https://api.githubcopilot.com/mcp/"
    credentials:
      vault: github-pat

Send JSON-RPC requests with POST /v1/mcp. GET /v1/mcp opens its Streamable HTTP server-push channel; GET /v1/mcp/sse is the dedicated-path spelling. Because tool calls frequently have side effects, set idempotency_safe: false on routes that carry them so the retry engine never replays a call. See MCP egress for static and dynamically resolved destinations, and Routes for retry behavior.

Related