Tool Provider Authorization#

Dify's tool provider authorization system controls how credentials are stored, fetched, and displayed for tools used in Agent and Workflow surfaces. The key architectural split is between builtin providers (plugin-based, managed via the plugin daemon with credentials stored in BuiltinToolProvider) and non-builtin providers (api, workflow, mcp, plugin) which use separate storage and different API routes. Routing the wrong provider type to a builtin API endpoint causes PluginNotFoundError (HTTP 500) — the root cause of issue #39169.

Provider types are enforced as a 7-value enum (builtin, api, plugin, workflow, mcp, app, dataset-retrieval) end-to-end as of PR #39380 1.

Frontend UI Gating#

Workflow Tool Node — Canvas Warning#

The canvas tool node (node.tsx) shows an "Authorization Required" warning badge when isToolAuthorizationRequired() returns true. The function requires all three conditions:

1. providerType === CollectionType.builtIn
2. collection.allow_delete === true
3. collection.is_team_authorization === false

Only builtin providers can trigger this warning. Non-builtin types (api, mcp, workflow) never show the badge 2.

Workflow Tool Node — Side Panel#

In the side panel, isShowAuthBtn (which gates the parameter form vs. auth prompt) uses the same isToolAuthorizationRequired() logic . When false, the tool input form is rendered normally; when true, the auth prompt replaces it.

Agent Tool Selector — Auth Section#

In the agent tool detail panel, ToolAuthorizationSection renders only when currentProvider.type === CollectionType.builtIn && currentProvider.allow_delete. For all other provider types, it returns null. When it does render, it mounts PluginAuthInAgent, which calls usePluginAuth and renders either an Authorize or Authorized credential picker. The picker always includes a "Workspace Default" synthetic entry (__workspace_default__) alongside per-user credentials 4.

Credential Schema Routing#

useGetApi Hook#

All plugin-auth API URLs are resolved by useGetApi, which branches on category from PluginPayload:

• AuthCategory.tool → URLs point to /workspaces/current/tool-provider/builtin/<provider>/... 5
• AuthCategory.datasource → URLs point to /auth/plugin/datasource/<provider>/... 6
• All other categories → returns an all-empty-string object that silently prevents requests

For builtin tools, the key credential endpoints are:

enabled Gating Pattern#

Every useQuery call in the plugin-auth hooks checks enabled: !!url. When useGetApi returns an empty string for a given URL, that query is silently disabled — no request fires, no error surfaces.

Bug & Fix: Non-Builtin Providers Hitting Builtin Routes#

Issue #39169: On the Agents configure page, custom API tool providers triggered requests to GET /tool-provider/builtin/<id>/credential/info. Since custom API providers have no plugin daemon entry, the backend raised PluginNotFoundError → HTTP 500 on every page load 7.

PR #39206 applied two layers of defense 8:

1. Hook-level (use-get-api.ts): When category === AuthCategory.tool, providerType is provided, and providerType !== CollectionType.builtIn, the hook now returns EMPTY_API (all empty-string URLs). The enabled: !!url gate then prevents all requests. Callers that omit providerType (legacy sites) still receive builtin URLs for backward compatibility.

2. Component-level (CredentialStatus in item.tsx): An isBuiltinProvider guard returns null before usePluginAuth is even invoked for non-builtin providers — preventing both the API call and the misleading "Not Authorized" UI.

Type Safety Enforcement — PR #39380#

PR #39380 replaced loose string-typed provider_type fields with a strict enum enforced at every boundary 1:

• Backend: AgentSoulDifyToolConfig.provider_type changed from optional str = "plugin" to required ToolProviderType Pydantic enum
• Generated contracts: packages/contracts/generated/api/console/agent/types.gen.ts exports ToolProviderType and a Zod validator zToolProviderType
• Frontend: A CollectionProviderType union combines CollectionType, DatasourceProviderType, and ToolProviderType for type-safe cache invalidation and URL routing

A secondary fix in this PR removed an unreachable builtin branch in datasource authorization that had been silently masking incorrect auth state.

Permission Hint Gating — PR #39721#

PR #39721 (merged 2026-07-29) tightened the showPermissionHint condition in plugin-auth.tsx 9. The "no permission" hint now requires both unauthorized state and !canCreateCredential — preventing false positives for users who can actually create credentials.

Key Files#