Implementation:Langgenius Dify PluginCredentialHooks

Knowledge Sources	Dify
Domains	Plugin Management Credential Management Authentication
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for managing plugin authentication credentials provided by the Dify plugin service layer via TanStack Query hooks.

Description

This module provides a comprehensive set of React hooks built on TanStack Query (useQuery and useMutation) for the full credential lifecycle. The hooks handle credential information retrieval, CRUD operations on credential entries, credential schema discovery for dynamic form generation, OAuth authorization URL retrieval, OAuth client schema management, and custom OAuth client configuration. All hooks accept dynamic URL parameters, allowing them to work with any plugin's credential endpoints without hardcoding paths.

The hooks are organized into three functional groups:

Credential CRUD: useGetPluginCredentialInfo retrieves the credential state for a plugin (including supported types and whether custom tokens are allowed). useAddPluginCredential creates a new credential entry. useUpdatePluginCredential modifies existing credentials. useDeletePluginCredential removes a credential entry. useSetPluginDefaultCredential designates a specific credential as the default.

Schema Discovery: useGetPluginCredentialSchema retrieves the FormSchema[] that drives dynamic form rendering. useGetPluginOAuthClientSchema retrieves the OAuth client configuration schema along with the current custom client state.

OAuth Management: useGetPluginOAuthUrl triggers generation of an OAuth authorization URL. useSetPluginOAuthCustomClient saves custom OAuth client parameters. useDeletePluginOAuthCustomClient removes a custom OAuth client configuration.

Usage

Use these hooks when:

• Building a credential management panel within plugin settings.
• Rendering dynamic credential forms from schema data.
• Implementing OAuth login flows that redirect to third-party authorization pages.
• Allowing workspace admins to configure custom OAuth applications for plugins.
• Managing multiple credential entries for a single plugin.

Code Reference

Source Location

• Repository: Dify
• File: web/service/use-plugins-auth.ts (lines 1-165)

Signature

// Credential information retrieval
export const useGetPluginCredentialInfo = (url: string) =>
  useQuery<{ allow_custom_token?: boolean; supported_credential_types: string[]; credentials: Credential[]; is_oauth_custom_client_enabled: boolean }>

// Set default credential
export const useSetPluginDefaultCredential = (url: string) =>
  useMutation<void, Error, string>  // mutationFn accepts credential id

// Get credential list
export const useGetPluginCredentialList = (url: string) =>
  useQuery

// Add a new credential
export const useAddPluginCredential = (url: string) =>
  useMutation<void, Error, { credentials: Record<string, any>; type: CredentialTypeEnum; name?: string }>

// Update an existing credential
export const useUpdatePluginCredential = (url: string) =>
  useMutation<void, Error, { credential_id: string; credentials?: Record<string, any>; name?: string }>

// Delete a credential
export const useDeletePluginCredential = (url: string) =>
  useMutation<void, Error, { credential_id: string }>

// Get credential form schema
export const useGetPluginCredentialSchema = (url: string) =>
  useQuery<FormSchema[]>

// Get OAuth authorization URL
export const useGetPluginOAuthUrl = (url: string) =>
  useMutation<{ authorization_url: string; state: string; context_id: string }>

// Get OAuth client configuration schema
export const useGetPluginOAuthClientSchema = (url: string) =>
  useQuery<{ schema: FormSchema[]; is_oauth_custom_client_enabled: boolean; is_system_oauth_params_exists?: boolean; client_params?: Record<string, any>; redirect_uri?: string }>

// Save custom OAuth client configuration
export const useSetPluginOAuthCustomClient = (url: string) =>
  useMutation<{ result: string }, Error, { client_params: Record<string, any>; enable_oauth_custom_client: boolean }>

// Delete custom OAuth client configuration
export const useDeletePluginOAuthCustomClient = (url: string) =>
  useMutation<{ result: string }>

Import

import {
  useGetPluginCredentialInfo,
  useSetPluginDefaultCredential,
  useGetPluginCredentialList,
  useAddPluginCredential,
  useUpdatePluginCredential,
  useDeletePluginCredential,
  useGetPluginCredentialSchema,
  useGetPluginOAuthUrl,
  useGetPluginOAuthClientSchema,
  useSetPluginOAuthCustomClient,
  useDeletePluginOAuthCustomClient,
} from '@/service/use-plugins-auth'

I/O Contract

Inputs

Name	Type	Required	Description
url	string	Yes	Dynamic API endpoint path for the plugin's credential operations
credentials	Record<string, any>	Yes (add/update)	Key-value pairs of credential field values matching the schema
type	CredentialTypeEnum	Yes (add)	The type category of the credential being created
name	string	No	Human-readable label for identifying the credential entry
credential_id	string	Yes (update/delete)	Unique identifier of the credential to modify or remove
id	string	Yes (set default)	Unique identifier of the credential to set as default
client_params	Record<string, any>	Yes (OAuth client)	Custom OAuth client configuration parameters (client_id, client_secret, etc.)
enable_oauth_custom_client	boolean	Yes (OAuth client)	Whether to enable the custom OAuth client

Outputs

Name	Type	Description
credentials	Credential[]	Array of stored credential entries for the plugin
allow_custom_token	boolean	Whether the plugin allows user-supplied tokens
supported_credential_types	string[]	List of credential type identifiers the plugin accepts
is_oauth_custom_client_enabled	boolean	Whether a custom OAuth client is currently active
FormSchema[]	array	Array of form field descriptors for rendering credential input forms
authorization_url	string	OAuth provider URL to redirect the user for authorization
state	string	CSRF protection state parameter for the OAuth flow
context_id	string	Server-side context identifier linking the OAuth flow to the plugin
schema	FormSchema[]	OAuth client configuration form fields
redirect_uri	string	The callback URL configured for the OAuth flow
result	string	Operation result indicator for mutation responses

Dependencies

Dependency	Purpose
@tanstack/react-query (useQuery, useMutation)	Declarative data fetching with caching, refetching, and mutation lifecycle management
@/service/base (get)	HTTP GET for query functions
@/service/base (post)	HTTP POST for mutation functions
@/service/base (del)	HTTP DELETE for the OAuth client deletion hook
@/service/use-base (useInvalid)	Cache invalidation helper for refreshing queries after mutations

Usage Examples

import {
  useGetPluginCredentialInfo,
  useAddPluginCredential,
  useGetPluginCredentialSchema,
  useGetPluginOAuthUrl,
} from '@/service/use-plugins-auth'

function PluginCredentialPanel({ pluginId }: { pluginId: string }) {
  const baseUrl = `/workspaces/current/plugin/${pluginId}/credentials`

  // 1. Get current credential state
  const { data: credentialInfo } = useGetPluginCredentialInfo(`${baseUrl}/info`)

  // 2. Get schema for dynamic form rendering
  const { data: schema } = useGetPluginCredentialSchema(`${baseUrl}/schema`)

  // 3. Add a new credential
  const addCredential = useAddPluginCredential(`${baseUrl}/add`)
  const handleSave = (values: Record<string, any>) => {
    addCredential.mutate({
      credentials: values,
      type: 'api_key',
      name: 'My API Key',
    })
  }

  // 4. Initiate OAuth flow
  const getOAuthUrl = useGetPluginOAuthUrl(`${baseUrl}/oauth/url`)
  const handleOAuth = async () => {
    const result = await getOAuthUrl.mutateAsync()
    window.location.href = result.authorization_url
  }

  return (
    // Render form using schema and credentialInfo...
  )
}

Related Pages

Implements Principle

• Principle:Langgenius_Dify_Plugin_Credential_Configuration