Builtin Tool Provider Credentials#

Overview#

Builtin tool provider credentials are per-tenant API keys or OAuth tokens that Dify stores so providers like Google Search or DALL-E can authenticate against external APIs. Each workspace can hold up to 100 credential sets per provider 1. Credentials are persisted in the BuiltinToolProvider table with the following key fields 2:

The main components involved:

API Endpoints#

All builtin credential endpoints live under /workspaces/current/tool-provider/builtin/<provider>/.

Request payload models are BuiltinToolAddPayload 3 and BuiltinToolUpdatePayload 4. Add carries a type: CredentialType field that is immutable once saved; update takes a credential_id to identify which saved set to modify.

The /credentials GET accepts an include_credential_ids list so that workflow/agent nodes can request credential sets owned by other members that would otherwise be hidden by visibility filtering — those rows are returned with from_other_member=True 5.

Add and Update Flow#

Adding a credential (add_builtin_tool_provider)#

add_builtin_tool_provider runs inside a single DB transaction and follows this sequence:

1. Redis lock — acquires builtin_tool_provider_create_lock:{tenant_id}_{provider} with a 20-second timeout to prevent duplicate concurrent creates 6.
2. Provider count check — rejects the request if the tenant already has 100 credentials for this provider 7.
3. Credential validation — if CredentialType.is_validate_allowed() is true, calls provider_controller.validate_credentials(user_id, credentials), which makes a live request to the external API 8.
4. Name generation — auto-generates an incremental name if none is supplied; rejects duplicate names 9.
5. Encryption — creates a ProviderConfigEncrypter via create_provider_encrypter() with a NoOpProviderCredentialCache (no caching for brand-new rows) and stores json.dumps(encrypter.encrypt(credentials)) 10.
6. Persist — inserts a new BuiltinToolProvider row with the chosen visibility enum 11. PARTIAL_TEAM visibility is rejected at this layer 12.

Updating a credential (update_builtin_tool_provider)#

update_builtin_tool_provider is similar but targets an existing row by credential_id:

1. Fetches the BuiltinToolProvider row; raises if not found 13.
2. Skips credential changes unless the type is_editable() and new credentials were submitted.
3. HIDDEN_VALUE handling — decrypts existing credentials first, then replaces any HIDDEN_VALUE placeholders in the incoming payload with the original values, preventing accidental overwrite of masked secrets 14.
4. Validates the merged credential set if allowed 15.
5. Re-encrypts and saves; calls cache.delete() to evict the Redis-cached decrypted value 16.
6. Visibility is immutable after creation — update has no path to change it 17.

Encryption#

All credential values are encrypted at rest via create_provider_encrypter(tenant_id, config, cache), which returns a (ProviderConfigEncrypter, ProviderConfigCache) tuple. The config argument is built from the provider's credential schema (get_credentials_schema_by_type()), so only declared sensitive fields are encrypted.

The service has two helper patterns:

• create_tool_encrypter() 18 — for existing BuiltinToolProvider rows; attaches a live ToolProviderCredentialsCache keyed on the row's id.
• Inline create_provider_encrypter() with NoOpProviderCredentialCache 19 — used during creation before a row id exists; skips caching.

When serving credentials back to the API, the service decrypts and then calls encrypter.mask_plugin_credentials() to replace sensitive values with HIDDEN_VALUE before serialization 20.

Redis Cache#

Decrypted credentials are cached in Redis by ToolProviderCredentialsCache:

• Key pattern: tool_credentials:tenant_id:{tenant_id}:provider:{provider}:credential_id:{credential_id}
• TTL: 86 400 seconds (24 hours) 21

Every mutating operation (update, delete) explicitly calls cache.delete() to evict the stale entry. NoOpProviderCredentialCache is used when no caching is desired — during initial creation (before the row has an id) and for OAuth client operations 22.

Redis Lock Timeout on Add#

The creation path acquires redis_client.lock(lock_key, timeout=20) — a plain redis-py lock with a 20-second TTL 6. This guards against duplicate concurrent inserts for the same tenant_id + provider.

Timeout risk: If provider_controller.validate_credentials() calls an external API that takes longer than 20 seconds, the lock expires before the transaction completes. A second concurrent request can then acquire the lock and insert a duplicate row. The provider count cap (100) is the only backstop.

The auto-renewing DbMigrationAutoRenewLock pattern (which heartbeats to extend the TTL) is not used here — its module docstring explicitly warns it is "migration-specific" and that callers should "prefer explicit lock lifecycle management" for normal application code 23. Engineers who need to extend the lock window for slow validations should either shorten the validation timeout or switch to redis_client.lock(...).extend() from within the same thread.