Implementation:Langgenius Dify Plugin Auth Hooks

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

Overview

Description

The Plugin Auth Hooks module (web/service/use-plugins-auth.ts) provides 12 React hooks built on TanStack Query that manage the complete lifecycle of plugin credential configuration. These hooks are organized into four functional groups:

Credential information and listing -- useGetPluginCredentialInfo, useInvalidPluginCredentialInfo, useGetPluginCredentialList
Credential CRUD -- useAddPluginCredential, useUpdatePluginCredential, useDeletePluginCredential, useSetPluginDefaultCredential
Credential schema -- useGetPluginCredentialSchema
OAuth flow -- useGetPluginOAuthUrl, useGetPluginOAuthClientSchema, useSetPluginOAuthCustomClient, useDeletePluginOAuthCustomClient

The OAuth popup flow is handled by the companion openOAuthPopup utility from web/hooks/use-oauth.ts, which opens a centered browser popup, listens for postMessage callbacks, and includes a fallback polling mechanism for popup close detection.

Usage

All hooks accept a URL parameter that is dynamically constructed based on the plugin and provider being configured. This URL-parameterized design allows the same hooks to work with any plugin's credential endpoints without hardcoding paths.

Code Reference

Source Location

web/service/use-plugins-auth.ts (Lines 15--165) and web/hooks/use-oauth.ts (Lines 41--73)

Signature

// Credential info and listing
export const useGetPluginCredentialInfo = (url: string) => {
  return useQuery({
    enabled: !!url,
    queryKey: [NAME_SPACE, 'credential-info', url],
    queryFn: () => get<{
      allow_custom_token?: boolean
      supported_credential_types: string[]
      credentials: Credential[]
      is_oauth_custom_client_enabled: boolean
    }>(url),
    staleTime: 0,
  })
}

// Credential CRUD
export const useAddPluginCredential = (url: string) => {
  return useMutation({
    mutationFn: (params: {
      credentials: Record<string, any>
      type: CredentialTypeEnum
      name?: string
    }) => {
      return post(url, { body: params })
    },
  })
}

export const useUpdatePluginCredential = (url: string) => {
  return useMutation({
    mutationFn: (params: {
      credential_id: string
      credentials?: Record<string, any>
      name?: string
    }) => {
      return post(url, { body: params })
    },
  })
}

export const useDeletePluginCredential = (url: string) => {
  return useMutation({
    mutationFn: (params: { credential_id: string }) => {
      return post(url, { body: params })
    },
  })
}

// OAuth flow
export const useGetPluginOAuthUrl = (url: string) => {
  return useMutation({
    mutationKey: [NAME_SPACE, 'oauth-url', url],
    mutationFn: () => get<{
      authorization_url: string
      state: string
      context_id: string
    }>(url),
  })
}

// OAuth popup utility
export const openOAuthPopup = (url: string, callback: (data?: any) => void) => {
  const popup = window.open(url, 'OAuth', `width=600,height=600,...`)
  window.addEventListener('message', handleMessage)
  // Fallback close detection via setInterval
  return popup
}

Import

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

import { openOAuthPopup } from '@/hooks/use-oauth'

I/O Contract

useGetPluginCredentialInfo

Direction	Field	Type	Description
Input	url	`string`	The credential info endpoint URL for the plugin
Output	allow_custom_token	`boolean`	Whether custom tokens are permitted
Output	supported_credential_types	`string[]`	List of supported credential types
Output	credentials	`Credential[]`	Existing credentials for this plugin
Output	is_oauth_custom_client_enabled	`boolean`	Whether custom OAuth client is active

useAddPluginCredential

Direction	Field	Type	Description
Input	credentials	`Record<string, any>`	The credential key-value pairs
Input	type	`CredentialTypeEnum`	The credential type (api_key, oauth, etc.)
Input	name	`string` (optional)	A human-readable name for the credential
Output	(server response)	varies	Confirmation of credential creation

useGetPluginOAuthUrl

Direction	Field	Type	Description
Input	url	`string`	The OAuth URL generation endpoint
Output	authorization_url	`string`	The OAuth provider's authorization URL
Output	state	`string`	The CSRF state parameter
Output	context_id	`string`	A context identifier for correlating the callback

openOAuthPopup

Direction	Field	Type	Description
Input	url	`string`	The OAuth authorization URL to open
Input	callback	`(data?: any) => void`	Callback invoked with the OAuth result or undefined on close
Output	popup	null	The popup window reference

Usage Examples

Adding an API key credential

const { mutateAsync: addCredential } = useAddPluginCredential(
  '/workspaces/current/plugin/openai/credentials/add'
)

await addCredential({
  credentials: { api_key: 'sk-...' },
  type: CredentialTypeEnum.API_KEY,
  name: 'Production API Key',
})

Initiating an OAuth flow

const { mutateAsync: getOAuthUrl } = useGetPluginOAuthUrl(
  '/workspaces/current/plugin/github/oauth/url'
)

const { authorization_url } = await getOAuthUrl()
openOAuthPopup(authorization_url, (data) => {
  if (data?.success) {
    // OAuth completed successfully, refresh credential info
    invalidateCredentialInfo()
  }
})

Configuring a custom OAuth client

const { mutateAsync: setCustomClient } = useSetPluginOAuthCustomClient(
  '/workspaces/current/plugin/slack/oauth/custom-client'
)

await setCustomClient({
  client_params: { client_id: '...', client_secret: '...' },
  enable_oauth_custom_client: true,
})

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment