Skip to main content

Virtual Keys, Providers, and Models

Three resources separate an application's identity from provider credentials and physical model names.

Relationship between Virtual Keys, Model Aliases, Providers, and Provider Models

Application credential     Stable application name       Upstream configuration
Virtual Key           +    Model Alias              ->   Provider + provider model

Virtual Key​

A Virtual Key identifies a calling workload and belongs to one Team. It controls whether the caller is active and can carry request/token limits, a governance policy reference, and upstream retry overrides.

The plaintext value is returned when created and only a hash is retained for later lookup. Losing the plaintext therefore requires key rotation or replacement; it cannot be recovered from the platform.

Virtual Keys should be separated by application, environment, or trust boundary. Sharing one key across unrelated workloads makes revocation, usage attribution, and limit tuning ambiguous.

Provider​

A Provider describes an upstream AI service: its type, endpoint, activation state, credential material, and provider-specific configuration. Provider credentials belong to the control plane and are not the same as Virtual Keys:

  • Virtual Key: client to Taimoe authentication.
  • Provider credential: Taimoe to the upstream provider authentication.

Providers can expose one or more Provider Models. Actual provider support depends on the active gateway adapter and credential method; a provider type being present in configuration does not by itself guarantee full request-protocol support.

Provider Model and Model Alias​

A Provider Model records a model available from a Provider and its capabilities. A Model Alias maps a stable name used by applications to a Provider and upstream model identifier.

For example, an application can call support-fast while administrators change which approved upstream model that alias targets. This keeps provider-specific model IDs out of application configuration and gives governance rules a stable resource to reference.

An alias change can change latency, quality, cost, region, and model behavior. Treat it as a production configuration change even when client code remains unchanged.

Resolution invariant​

The caller authenticates first, then Taimoe resolves the alias and checks permission before contacting the Provider. Clients should never receive or need the Provider credential.

See the AI Gateway request lifecycle for the complete sequence and the User Guide pages for Virtual Keys, Providers, and Models.