What you’ll learn:
- What providers, provider deployments, configs, and auth configs are
- How these entities relate to each other
- How to mix and match them when creating sessions
Providers
A provider is an integration available in the Metorial catalog—for example Slack, GitHub, Exa, or Tavily. Each provider has one or more versions, and each version defines:- The tools the provider exposes (with input/output schemas)
- The authentication methods it supports
- The configuration fields it accepts
Provider Deployments
A provider deployment is a running instance of a provider. When you deploy a provider from the catalog, Metorial creates a provider deployment for it. By default, a provider deployment always uses the latest version of the provider. You can optionally pin a deployment to a specific version to prevent automatic updates—useful when you need stability across a production environment.Every deployment has a unique ID (
pdp_...). You use this ID when creating sessions.Provider Configs
A provider config stores the configuration values for a provider deployment—things like endpoint URLs, feature flags, or other settings specific to that provider. Provider configs are linked to a provider and can optionally be locked to a specific provider deployment. This lets you have multiple configs for the same provider (e.g. one for a staging environment, one for production). You can also link a provider config to a Provider Config Vault entry, which stores a reusable config template you can apply across multiple deployments.Not all providers require configuration. If a provider has no required config fields, Metorial auto-creates a default config when you create a session.
Provider Auth Configs
A provider auth config stores the authentication credentials for a specific user’s connection to a provider. This is where OAuth tokens and manual API keys live. There are three types:| Type | Description |
|---|---|
manual | Credentials entered directly (e.g. an API key for Exa or Tavily) |
oauth_automated | OAuth tokens obtained via a Provider Setup Session |
oauth_manual | OAuth tokens imported manually |
Provider Setup Sessions
A provider setup session is the flow you use to get a user authenticated with a provider. You create a setup session and redirect your user to its URL—they complete the auth flow (OAuth or manual config entry), and when they finish, Metorial creates a provider auth config automatically. Setup sessions support three modes:| Mode | Use when |
|---|---|
auth_only | The provider needs authentication but no config |
config_only | The provider needs configuration but no auth |
auth_and_config | The provider needs both |
pending → completed / expired / failed).
See OAuth Integrations for the full setup flow.
How These Entities Compose
When creating a session, you attach one or more provider deployments to it. Metorial uses the deployment to look up the provider and then figures out what else it needs:- If the provider requires authentication, you must supply a matching provider auth config—or create one first via a setup session.
- If the provider requires configuration, you must supply a provider config—or Metorial creates a default one automatically.
- You always need at least a provider deployment (or enough information to find one) for each provider in the session.
Metorial auto-creates missing pieces where possible. For example, if a provider has no required config fields, you don’t need to create a config manually—Metorial creates a default one for the session.