Skip to main content
Meerkat separates where a provider request goes from how that request is authorized. Sessions refer to a binding, and the binding joins one backend profile to one auth profile.
This lets one process use several provider accounts or tenants, give mob members different credentials, and re-resolve credentials on resume without putting secret material in the session transcript or metadata.

​
The Five Identities

The backend profile and auth profile must name the same provider, and that provider must support the selected backend_kind and auth_method pair. Meerkat validates the combination before constructing the provider client. Without credential_account, the binding itself remains the credential identity. With it, route selection still uses the binding while token storage, refresh locking, login state, status, and logout use the realm-scoped account. This is how the three GitHub Copilot provider-family routes share one sign-in. For self-hosted models, the backend profile can also identify the specific self_hosted.servers.<id> entry it authenticates. This prevents a credential for one OpenAI-compatible server from being selected for another server merely because both use the self_hosted provider class.

​
Binding Selection

A realm can declare one default_binding, and a binding can set provider_default = true to become the default for its provider. An explicit auth_binding always names the intended configured binding directly. When the model is omitted, session creation resolves in this order:
  1. An explicit binding’s default_model, if present.
  2. A configured model compatible with the explicit provider or binding.
  3. That provider’s catalog default.
  4. With no provider/binding constraint, the configured global model and then catalog defaults.
An explicit model still wins, but a known provider/model mismatch fails before agent construction.

​
Structural References

Public JSON surfaces use an object:
The CLI accepts prod:openai or prod:openai:optional-profile as an input convenience and converts it to the structural form at the CLI boundary. Runtime and persistence contracts do not carry the joined string. Configured references have origin = "configured" (the serialized default). The environment-variable fast path uses a typed origin = "synthetic_env_default"; it is ephemeral and is not a durable realm that can be configured or inherited.

​
Sessions Keep Intent, Not Secrets

SessionMetadata.auth_binding persists the binding reference used by a session. On resume or a model hot-swap, the factory re-resolves that reference against the effective realm config and obtains a fresh credential lease. Access tokens and API keys are never stored in session metadata. If a turn changes provider, supply a matching model and binding together. Leaving the binding unchanged preserves the existing account intent and will fail closed if it is incompatible with the new provider.

​
Inheritance And Ownership

Realm config is resolved through its configured parent chain and an optional global tail:
  • Binding reads inherit. A workspace realm can use a binding defined in a parent or in global.
  • Credential writes are strict-owner and explicitly addressed. Login, logout, refresh, and managed credential persistence must name the realm that defines the binding. A child-addressed inherited write is rejected with the owner; the service does not forward it automatically.
  • A resolved inherited binding retains its owning realm as provenance. That realm keys managed credentials and auth leases.
This is why rkat auth login, which provisions global, works from every workspace without copying the credential into each workspace config.

​
Credential Sources

An auth profile can resolve credentials from environment variables, the managed token store, an inline secret, a platform default chain, a host resolver, a command, or a host-supplied file descriptor. Availability depends on the auth method and build features. Use environment variables for the simplest local path. Use managed-store OAuth or an explicit host resolver when account identity, refresh, or tenant isolation matters.

​
See Also