Plugin Credential Management#

Overview#

Plugin credential management in Dify covers how plugins declare, render, and validate credential input forms through YAML schema definitions in provider manifest files. The YAML schema drives both the frontend form UI and the runtime credential validation logic — there is no separate schema registration step.

Credentials live in the provider YAML file (provider/<name>.yaml) under one of two top-level keys depending on plugin category:

Tool Plugin: credentials_for_provider#

Tool providers define a flat YAML map under credentials_for_provider. Each key becomes the variable name passed to the Python _validate_credentials method and available during tool invocation.

Reference: Google provider YAML

Supported fields per credential entry:

Multiple credentials: Salesforce provider YAML defines four fields — username (text-input), password (secret-input), security_token (secret-input), domain (optional text-input) — illustrating how multiple credentials of different types are declared in a single provider.

_validate_credentials implementation#

The Python provider class receives the submitted credential dict and must raise ToolProviderCredentialValidationError on failure. Common patterns:

• Test invoke: Instantiate the tool and run a test query — Google provider
• Live API call: Build a client and call a lightweight endpoint — OpenAI tool provider
• HTTP auth check: Make an authenticated REST request and inspect HTTP status — Google Tasks provider
• Format-only check: Validate URL/string format without a network call — Slack provider

Model Plugin: provider_credential_schema and model_credential_schema#

Model providers use a different structure with a credential_form_schemas list. Fields are identical to tool credential fields but use a variable key instead of the map key as the identifier.

Reference: Full examples in openai.yaml and moonshot.yaml.

validate_model parameter#

Model provider credential forms include an optional validate_model field in provider_credential_schema.credential_form_schemas. This is a conventional text-input credential variable — not a reserved keyword — that lets users (or the plugin default) specify which model to use for the credential test ping.

• OpenAI: validate_model defaults to "gpt-4o-mini" at the Python level 1
• Moonshot: defaults to "kimi-k2-0711-preview" 2

In validate_provider_credentials, the provider reads credentials.get("validate_model") and passes that model name to model_instance.validate_credentials(). This allows users who only have access to specific models (e.g., behind a billing tier) to override the default test model without changing code.

Model Credential Schema Scopes: provider_credential_schema vs model_credential_schema#

Model plugins support two scopes:

• provider_credential_schema: Used when configurate_methods includes predefined-model. One set of credentials covers all predefined models. The validate_model field typically lives here.
• model_credential_schema: Used when configurate_methods includes customizable-model. Credentials are set per custom model. The schema includes a model block (label + placeholder for the model name field) alongside credential_form_schemas. See moonshot.yaml for a full example with both scopes defined.

Key Source Files#

For the API/service layer that stores, encrypts, and Redis-caches submitted credentials after the form is submitted, see the Builtin Tool Provider Credentials article 3.