Principle:Langgenius Dify Plugin Credential Configuration

Knowledge Sources	Dify
Domains	Plugin_System, Marketplace, Frontend
Last Updated	2026-02-12 00:00 GMT

Overview

Description

Plugin Credential Configuration governs how the Dify frontend manages authentication credentials for installed plugins. Plugins often require API keys, OAuth tokens, or other secrets to function. This principle establishes a hook-based credential management layer built on TanStack Query (React Query), providing 12 specialized hooks that cover the full credential lifecycle: introspection (schema and info retrieval), CRUD operations (add, update, delete), default selection, and OAuth flow management.

The credential system supports two authentication paradigms:

Static credentials -- API keys and tokens entered manually by the user, stored via the credential CRUD hooks.
OAuth credentials -- Tokens obtained through a browser popup OAuth flow, where the frontend opens an authorization URL in a popup window and listens for callback messages via window.postMessage.

The OAuth flow additionally supports custom OAuth clients, allowing workspace administrators to configure their own OAuth application credentials (client ID, client secret) rather than using system-provided defaults.

Usage

Credential Configuration is used whenever a plugin declares that it requires authentication. The typical flows are:

Viewing credential requirements -- useGetPluginCredentialInfo retrieves supported credential types and existing credentials.
Adding/updating credentials -- useAddPluginCredential and useUpdatePluginCredential submit credential payloads.
OAuth authorization -- useGetPluginOAuthUrl fetches the authorization URL, and openOAuthPopup opens it in a centered popup window. The popup posts the result back to the opener window via window.postMessage.
Custom OAuth client management -- useGetPluginOAuthClientSchema retrieves the form schema for custom client parameters, and useSetPluginOAuthCustomClient saves custom client configuration.

Theoretical Basis

The credential configuration system applies several established patterns:

Hooks as use-case boundaries -- Each hook encapsulates exactly one credential operation, following the Single Responsibility Principle. This makes each hook independently testable and composable.
Query/Mutation separation -- Read operations (info, list, schema) use useQuery with cache keys for automatic deduplication and background refresh. Write operations (add, update, delete) use useMutation with explicit invalidation, following TanStack Query's recommended patterns.
Popup-based OAuth -- The OAuth flow uses window.open with postMessage communication, which is the standard browser-native pattern for third-party OAuth without full-page redirects. The openOAuthPopup utility includes both message-based and poll-based close detection for robustness.
Schema-driven forms -- Credential input forms are generated from FormSchema[] definitions retrieved at runtime, following the Interpreter pattern where the UI renders dynamically based on server-provided metadata.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment