Reference

Providers and authentication

Understand provider, transport, model, reasoning, and credential choices before changing a Buffaly session or storing secrets.

A complete Buffaly model selection is not just a model name. It is a validated tuple of provider, transport, model, reasoning level, and the authentication route required by that transport.

Quick terms

Term	User-facing meaning	Verified notes
Provider	The AI family or vendor token, such as `openai`, `xai`, or `gemini`.	Built-in tokens are defined by `ProviderCatalogDefaults`; modules can add more catalog sources.
Transport	The execution route used for a provider.	Verified transport tokens include `codex_backend`, `responses_api`, and `provider_native`.
Model	The concrete model name available under one provider and transport.	`ProviderCatalogService` resolves model rows after provider and transport validation.
Reasoning level	A model-scoped reasoning-effort token, when supported.	Reasoning is validated against each model row; unsupported levels fail explicitly.
Authentication	The credential or login route needed by the selected transport.	OpenAI API-key settings, Codex backend auth/profile settings, and provider-native module credentials are separate concepts.
Provider module	An optional extension that contributes provider catalog rows or provider-native completion executors.	`DynamicProviderModuleLoader` reads enabled rows from `ProviderModules.json` under the install-root provider modules folder.

Provider identity is not transport

Do not treat OpenAI, Codex, API key, Grok, and Gemini as interchangeable. Buffaly separates the identity of a provider from the route used to call it, and each route can have different model catalogs, tool support, structured output behavior, prompt caching, compaction support, and authentication.

OpenAI through Codex backend

provider: openai

transport: codex_backend

model: catalog model such as gpt-5.5

auth route: Codex auth/profile/backend settings

Provider-native module

provider: xai or gemini when installed

transport: provider_native

model: provider catalog model

auth route: provider-specific feature rows or provider-auth profile

Documented providers and transports

The source tree shows built-in/default concepts for OpenAI, xAI, Gemini, Codex backend, Responses API, provider-native transport, and an OpenAI default model token of gpt-5.5. Treat those as source-grounded tokens, not proof that a deployment has every provider configured.

The provider catalog source registry starts with OpenAiCodexProviderCatalogSource and appends dynamic provider catalog sources from installed provider modules.
OpenAI through codex_backend is documented built-in provider catalog behavior.
Optional provider-native providers such as Anthropic, xAI, or Gemini are deployment/configuration dependent until catalog rows and feature rows verify them.

Operator rule: do not call a provider available just because source supports it. Verify the catalog, module manifest, feature rows, credentials, and a small smoke test in the running instance.

Grok authentication with xAI OAuth

Grok is exposed as provider xai through provider_native when the xAI provider module is installed. Current xAI OAuth support uses Buffaly's generic provider-auth profile system: the provider module owns xAI protocol details, while the host owns login lifecycle, profile storage, active-profile selection, and runtime bearer credential resolution.

Buffaly asks the xAI provider-auth handler to begin login.
The handler discovers authorization and token endpoints from https://auth.x.ai/.well-known/openid-configuration.
The handler generates a PKCE verifier/challenge, state, and nonce.
The Settings Grok sign-in UI opens an xAI authorize URL with plan=generic and referrer=buffaly.
The user signs in with xAI/SuperGrok in the browser.
Buffaly completes login from the browser callback or pasted callback/code path and exchanges the code for tokens.
Buffaly stores the provider-auth profile under the install's sessions root, scoped by provider key.
Runtime provider-native calls resolve the active xAI profile and pass its OAuth access token as the bearer credential.

OAuth profile is not an API key

A profile can include access token, refresh token, token type, expiry, base URL, and recommended transport. The xAI Responses API still receives the credential through Authorization: Bearer <credential>.

Precedence

For provider-native xAI calls, an active provider-auth profile wins. If no active profile exists, xAI falls back to legacy XAI Feature or XAI.ApiKey settings.

To use OAuth, sign in under Settings > Grok and keep an active xAI profile selected. To use a legacy API key, remove or deactivate the active xAI profile and configure the target instance's xAI API-key settings.

Never paste secrets: do not put xAI access tokens, refresh tokens, API keys, authorization codes, or full callback URLs into prompts, tickets, wiki pages, logs, or commits.

What can safely be called the default provider?

The safe default-provider statement is narrow: OpenAI via Codex backend is the built-in/default route in product implementation. That does not mean every installed Buffaly instance has a valid Codex profile, token file, backend access, or live model list.

Fallback behavior

Omitted provider tokens normalize to openai.
OpenAI defaults to codex_backend.
Other provider tokens default to provider_native.
A session without usable persisted selection falls back to OpenAI/Codex with medium reasoning as a seed.

Verify the installed default

Inspect provider catalog DefaultSelection, provider rows, enabled transports, default model, IsConfigured, and errors.
Check ProviderCatalogService.GetProviderSelection(sessionKey) for the active session.
Confirm UI selectors show the expected provider/model/reasoning options.
Run a small smoke test only after catalog validation passes.

Codex backend authentication versus OpenAI API authentication

OpenAI API-key authentication and Codex backend authentication are separate settings. The selected transport determines which credential path matters.

Route	Where to check	What it controls
OpenAI API-key route	`OpenAI Feature` / `OpenAIFeature.ApiKey`	Conventional OpenAI API-key setting.
Codex auth/profile route	`Codex Auth Feature` / `CodexAuthFeature`	Auth mode, token file/root paths, OAuth-style endpoints, callback settings, and refresh settings.
Codex backend route	`Codex Backend Feature` / `CodexBackendFeature`	Backend base URL, endpoint path, default model, timeout, user agent, and backend toggles.

BaseUrl: https://chatgpt.com/backend-api
EndpointPath: codex/responses
DefaultModel: gpt-5.5
UserAgent: BuffalyCodexBackend/1.0

If the selected transport is codex_backend, inspect Codex Auth and Codex Backend settings before assuming OpenAI Feature.ApiKey is relevant. If a route is using conventional OpenAI API keys, inspect OpenAI Feature and keep it separate from Codex profile/backend settings.

How the provider catalog validates selections

ProviderCatalogService is the validation boundary for provider selection. It builds a catalog from registered sources, resolves a default selection, and validates provider, transport, model, and reasoning together.

The requested provider must exist and be enabled.
The requested transport must exist for that provider and be enabled.
The requested model must exist for the selected provider/transport.
The selected reasoning level must be supported by that model.
A provider catalog with no provider rows, no enabled/default transport, or no default model is an error.

This strict behavior is safer than silently switching providers, dropping tool support, or downgrading reasoning. If selection fails, diagnose the tuple instead of changing one field at a time until the error disappears.

How users configure providers and credentials

Configuration is deployment-specific. Keep selection paths separate from credential paths: the main Buffaly agent UI and provider catalog APIs expose provider, transport, model, and reasoning selection; settings UI and feature rows expose credentials and auth configuration.

What to configure	Verified place to check	Notes
OpenAI API-key route	`OpenAI Feature`	Conventional API-key setting. Do not expose the value.
Codex auth/profile route	`Codex Auth Feature`	Auth mode, token paths, endpoints, callbacks, and refresh behavior.
Codex backend route	`Codex Backend Feature`	Backend URL, endpoint path, default model, timeout, and toggles.
Optional provider-native modules	`<InstallRootPath>\lib\provider-modules\ProviderModules.json`	Dynamic loader reads enabled manifest rows and loads catalog sources and completion executors.
Provider-native credentials	Provider-specific feature rows/settings	Examples include Anthropic, xAI, and Gemini feature rows depending on the installed modules.
Provider selector UI/API	Provider catalog JsonWs and model-selection APIs	Expose provider/model/reasoning state to UI and runtime flows.

Adding a provider at a high level

Choose a stable provider token.
Provide a catalog source that implements IProviderCatalogSource.
Provide a provider-native completion executor when completions should run through provider_native.
Configure provider-specific feature settings and credentials in the target instance.
Add a ProviderModules.json entry that points to the module assembly and type names.
Verify the catalog shows the provider and an end-to-end completion works.

Practical examples

Diagnose provider configuration

Ask Buffaly to inspect the provider catalog, selected tuple, provider module manifest, and feature rows without printing secret values. The report should distinguish missing, disabled, unconfigured, and model/reasoning validation failures.

Verify model selection

Ask for provider, transport, model, reasoning level, and whether the selected model supports that reasoning level. Do not change the selection during read-only verification.

Remember a non-secret preference

Preferences such as using the highest validated reasoning level should be stored as normal memory or workflow notes, not as credentials.

Store credentials separately

Provider API keys should go through the secret or credential path, not ontology memory, Scratch, markdown, tickets, or docs examples.

Troubleshooting and verification

When provider selection is confusing, verify the tuple and credential path in order.

Catalog: confirm the provider appears in the provider catalog.
Enabled/configured: check whether the provider is enabled and configured or whether the catalog returns an error.
Transport: confirm the selected transport is valid for that provider.
Model: confirm the model belongs to the selected provider/transport row.
Reasoning: confirm the requested reasoning level is supported by that model.
Auth route: check the credential path for that transport: OpenAI API key, Codex auth/backend settings, or provider-native feature rows.
Provider modules: if optional, verify <InstallRootPath>\lib\provider-modules\ProviderModules.json exists and points at loadable assemblies/types.
Diagnostics/logs: inspect loader diagnostics for missing manifests, assemblies, types, invalid interfaces, or exceptions.
Persistence: after setting selection, verify the active session persisted the same provider/transport/model/reasoning tuple.
Round trip: run a small completion smoke test only after catalog and selection validation pass.

Common failure modes

Provider module installed in the wrong install-root folder.
ProviderModules.json disabled, malformed, or using paths relative to the wrong folder.
Type name does not implement the required shared Web.Common interface.
Web app has catalog-source DLLs but the worker lacks completion-executor DLLs.
Feature row or credential is missing.
responses_api is assumed active just because it appears as a source token.
A model is changed without validating provider, transport, and supported reasoning levels.

Provider modules Secrets handling Provider models