How to manage Dify model provider API keys without sharing one key everywhere
A regulated team running Dify usually has several workspaces, development and production apps, and model endpoints from cloud providers and on-premises inference servers, each needing its own key. The decision to make early is whether those keys are separated by environment and owner or shared across everything. Sharing one key is the fastest way to start, but it means a leaked development key exposes production spend and data access, and rotating it touches every app at once. Dify lets you configure model provider credentials inside the platform, so the design question is where each key lives, who may change it and how it is retired.
Several Dify controls support a deliberate strategy. Within a provider you can keep more than one key, which lets development and production use separate credentials, and you can add custom model keys for models a provider does not list by default. You can also restrict who may manage model providers, so app builders can select a configured model without seeing or editing the secret. The Community edition of self-hosted Dify is free and limited to a single workspace, so separating keys across workspaces requires Dify Enterprise, which adds multiple workspaces and centralized management. Confirm with your Dify contact which of these controls apply to your edition and version before you write the policy.
Plan the rotation and assignment process before the first production app goes live. Dify Enterprise credential management lets system administrators configure vendor API keys once in the Admin Dashboard, assign them to workspaces, allow or forbid workspace-created credentials and rotate them centrally, which is the mechanism to evaluate against your change-control process. Record which key backs each workspace, who owns the provider account and how a key is revoked at the provider side as well as in Dify. Ask DeployOpen or your own engineers to test a rotation in staging first, because the SECRET_KEY and encryption settings in your environment also affect stored credentials and must be backed up separately.
Which key model fits your Dify environments
Within one workspace, a team can hold more than one credential for the same model provider, most often a development key and a production key. Workspace members with access to model provider settings manage these entries, so separation depends on people and naming discipline as much as on the software. Community is limited to a single workspace, so dev and prod cannot be split by workspace there, and this option is the most basic separation available.
- Who manages it: Workspace owners and admins who can edit model provider settings, with no central assignment step.
- Dev and prod separation: Apps draw from whichever key is selected for them, so separation holds only if dev and prod apps never share one workspace.
- Rotation: Each key is replaced by hand in every workspace that uses it, and affected apps must be tested afterward.
- Exports: Exported DSL files exclude third-party API keys, so a copied app needs its credential re-entered in the target workspace.
- Tracking: Dify does not give a central list of which key sits in which workspace, so keep that record in your own inventory.
Confirm in your Dify version which roles can view or change provider keys before relying on this model for production.
A custom model key attaches a credential to one specific model instead of the whole provider account. Teams use this when a single model needs its own key, for example because it has different access terms, a separate quota, or a dedicated endpoint. The person who configures that model in the workspace manages the key, usually the application owner or the platform team, so ownership is narrower than provider-level keys but still local to each workspace.
- Who manages it: Workspace members who add or edit that model, typically the application owner or platform team.
- Dev and prod separation: Useful for giving one model different keys in different environments, but each workspace holds its own copy, so entries multiply as environments grow.
- Rotation: Changing the key updates only the model it is attached to, which limits impact, but every custom entry across every workspace must be found and updated.
- Naming: Put the environment and model name in the credential label so reviewers can tell entries apart during a rotation.
- Mixed sources: A provider may carry both shared and custom keys, which makes the effective key behind an app harder to trace.
Ask for a list of every custom model entry per workspace and the apps that depend on each one before any rotation begins.
Dify Enterprise credential management lets system administrators configure plugin credentials, including model vendor API keys, once in the Admin Dashboard and assign them to workspaces. This is the only option in this comparison where workspace separation is governed centrally. Administrators can also allow or forbid workspace-created credentials, which determines whether teams can add keys outside the approved set. Because Community is single-workspace, multi-workspace dev and prod separation with central control depends on this edition.
- Who manages it: System administrators own the credentials, and workspace teams consume the assigned ones.
- Dev and prod separation: Create a distinct credential for each environment and assign it only to the workspaces that should use it.
- Workspace-created keys: Decide per environment whether workspaces may add their own keys, and forbid it for production.
- Rotation: Rotate in the Admin Dashboard so every assigned workspace receives the change without separate edits. Confirm how in-flight requests behave during the switch.
- Governance: Limit credential assignment to a named administrator group, aligned with your Enterprise SSO and workspace access model.
Confirm with Dify which assignment and rotation behaviors apply to your Enterprise version, including whether a rotation needs a restart or a maintenance window.
Configuration options and when each one fits
This table compares the credential controls that matter when a regulated team connects Dify to model providers. Read each row as a decision: what the option controls, the setup it suits, and what it costs you to operate. Confirm exact availability and defaults in the Dify version and vendor consoles you run, because not every control appears in every edition.
| Option | What it controls | Best fit | Trade-off |
|---|---|---|---|
| Multiple keys per provider | Lets one provider entry hold more than one API key so development and production traffic use different credentials and can be told apart in provider usage reports. | Teams that need separate spend limits, revocation paths or audit trails for staging and production. | Each key needs an owner, a rotation date and a record of where it is used. Confirm how many keys your Dify version supports per provider. |
| Custom model keys | Registers a specific model name and its credential against a provider so apps can call a model that is not in the default list. | Teams using fine-tuned models, private deployments or newly released models from a provider. | Custom entries must be re-checked after provider or Dify upgrades, since model names and API types can change. |
| Allowing workspace-created credentials | Lets workspace administrators add their own provider keys inside a workspace without central involvement. | Sandbox or innovation workspaces where teams experiment with low-risk data and throwaway keys. | Keys created outside central control are harder to inventory, rotate and revoke. Pair this with a review of who holds workspace admin rights. |
| Forbidding workspace-created credentials | Restricts workspaces to credentials that a system administrator has assigned to them. | Production workspaces and any workspace handling regulated or customer data. | Teams must file a request to add or change a provider, which adds lead time. Document the request path before enforcing it. |
| Central assignment from the Admin Dashboard | Lets a system administrator configure a vendor API key once and assign it to selected workspaces (Dify Enterprise credential management). | Organizations running several workspaces that share one contracted provider account. | Requires Dify Enterprise, which is custom priced. Confirm the assignment model with the vendor before designing workspace boundaries around it. |
| Central rotation | Lets administrators replace a credential in one place so every assigned workspace picks up the change. | Incident response, staff turnover and scheduled rotation under your key policy. | Rotation still needs a coordinated window with the provider console, since old keys must be revoked there. Test the change in a non-production workspace first. |
| Exports that exclude third-party API keys | DSL exports carry app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys. | Moving apps between staging and production without copying secrets into files or source control. | Imported apps need credentials reattached in the target environment. Plan that step in the promotion runbook and confirm the export contents for your version. |
Setting up provider keys for dev and production
This sequence separates development and production model provider keys in Dify, so that apps in each environment can only reach the credentials meant for them. It finishes with tested calls per environment and a named owner for rotation.
Confirm edition and workspace layout
Before creating any keys, record which Dify edition you run and how many workspaces exist or are planned. The Community edition of self-hosted Dify is limited to a single workspace, so separating development from production inside one instance is not possible there and requires a second deployment. Enterprise supports multiple workspaces and central credential management. Write down the workspace names, the environment each one serves, and who administers each. The check is a short table that every later step refers to, reviewed by the platform owner and the security lead.
Create separate vendor keys per environment
In each model provider's own console, create one API key for development and a different one for production, each with a clear name such as the environment and the owning team. Do not reuse a single key across both environments, because a leaked development key would then grant production access. Confirm with the provider how usage and spending limits can be set per key, and what the provider offers for project or organization separation. The output is an inventory listing each key's name, environment, and provider console location, without the secret values themselves.
Configure keys in each workspace or assign them centrally
In Community edition, open the model provider settings in the development workspace and add the development key, then do the same for production in its own instance. On Dify Enterprise, a system administrator configures the vendor credential once in the Admin Dashboard and assigns it to the specific workspaces that should use it, so the production key is assigned only to the production workspace. Where a provider supports multiple keys, confirm in the Dify docs how the active key is selected before relying on it. The check is that each workspace's provider list shows only the credential assigned to it.
Restrict who can create workspace credentials
Decide who may add or change provider credentials inside a workspace, and configure Dify so that workspace members cannot create their own credentials where the policy forbids it. On Enterprise, the credential management controls let administrators allow or forbid workspace-created credentials. Limit workspace administrator roles to named people, and keep app builders out of provider settings. The output is a written access list per workspace. The check is to sign in as a regular builder account and confirm that it cannot view or edit the provider credential pages.
Test a model call in each environment
From an app in the development workspace, run a test prompt against the chosen model and confirm the call succeeds. Then check the provider console usage view to confirm the request was counted against the development key, not production. Repeat the test in the production workspace with a non-sensitive prompt. Finally, confirm that an app in development cannot call the production key: if the development workspace has no production credential assigned, the attempt to select that model should fail or be unavailable. Record the date, the app, the key name and the result for each test.
Record the rotation owner and procedure
Name one owner for each provider key, along with a backup, and write the steps for rotating it: create the new key at the provider, update the credential in Dify, run a test call, then revoke the old key. On Enterprise, rotate the credential centrally so every assigned workspace picks up the change. Ask the provider how keys are revoked and whether revocation takes effect immediately. The output is a rotation record stored with the security runbook. The check is that the named owner can describe the procedure without referring to the Dify admin who configured it.
Security controls around Dify provider credentials
Provider keys in Dify are protected by several layers: the secret used to encrypt stored credentials, the place workspace encryption keys live, the proxy that filters outbound model calls, and the roles that decide who can change any of it. Each layer has a setting to review before production keys go in.
SECRET_KEY protects stored credentials
The SECRET_KEY variable signs session cookies and JWTs and is used to encrypt OAuth credentials, which includes the provider credentials saved in the console. Set it once, before any production keys are entered, and store it in your secrets manager rather than in a shared .env file. Changing it after deployment logs out all users, so treat rotation as a planned maintenance event. Confirm which secrets your deployment method reads from the environment and who can view them.
Workspace encryption key storage
The environment reference describes two places for workspace encryption keys: locally on the Dify host or in Azure Key Vault. Local storage keeps the key on the same machines that hold the database, so a single host compromise can expose both. Azure Key Vault moves key custody to a service your cloud team already audits. Confirm the option your version supports, who holds vault access, and how the key is backed up before you rely on it.
SSRF proxy blocks internal ranges
Model calls leave Dify as outbound HTTP requests. The SSRF_PROXY settings route those requests through a proxy that blocks internal and private IP ranges, which stops a misconfigured provider endpoint from reaching your internal services. Check that every model endpoint you register, including on-premises inference servers, is reachable through the proxy's allow rules. Test this with a private address to confirm the block works.
DSL exports exclude API keys
The Dify docs state that app exports include configuration, workflow nodes, prompts, model parameters and knowledge base connections, but not third-party API keys. This keeps keys out of files that teams copy between instances or attach to tickets. It does not remove the need for control, because the importing workspace must still hold its own valid credentials. Plan key re-entry or assignment as a step in every promotion between development and production.
Least privilege for provider management
Model provider settings affect every app in a workspace, so the people who can add, edit or delete provider credentials should be a short, named group. Separate them from people who only build and test apps. On Dify Enterprise, system administrators configure vendor keys in the Admin Dashboard and decide whether workspaces may create their own credentials. Review that group against your access policy each quarter and record the change.
Audit trail and logs to confirm
Ask your team to confirm which events are recorded when a provider key is created, changed, assigned or removed, who can read those records, and how long they are kept. Community deployments may need log export or a central logging agent to capture console activity. Enterprise administration features and their log scope should be checked against your version before you describe them to an auditor. Keep evidence of each key rotation with the change ticket.
Limits to confirm before you design the key model
Does my Dify provider plugin support more than one API key per provider?
Confirm this for each provider plugin and Dify version you run, because multiple-key support is a per-plugin behavior, not a platform-wide guarantee. Check the plugin's settings screen in a non-production workspace and see whether you can add, label and select several keys. If the plugin accepts only one key, separate development and production usage will need separate provider accounts or separate Dify instances. Record the answer in your design notes, since it determines whether one workspace can serve both environments safely.
How do custom model keys behave after a Dify upgrade?
Test this before every minor upgrade, because saved custom model configurations can change behavior when a provider plugin or API type changes. Export your current list of configured models and keys (outside Dify, in your secrets store), upgrade a copy of the environment, and confirm each custom model still resolves and responds. Also check the release notes for the target version on the Dify releases page, since minor releases arrive roughly monthly and a plugin update can alter how a saved key is read. Plan a backup before the upgrade, as the Docker Compose upgrade guidance recommends.
What happens to running apps when I rotate a provider key?
Rotating a key changes what every app using that credential calls, so confirm the impact in a staging copy before rotating production. Ask whether a new key takes effect immediately for all workspaces that reference the provider, whether old keys remain valid for a grace period on the provider side, and whether any apps hold a copy of the key outside Dify. Plan the rotation window with the owners of workflows, agents and scheduled jobs, and watch error rates during and after the change. Exports of app DSL files do not include third-party API keys, so each environment needs its own credential entry.
Which credential management features are included in my Dify Enterprise release?
Confirm the credential management feature set against the documentation for your exact Enterprise version, because capabilities such as central configuration, workspace assignment and workspace credential restrictions depend on the release. The Enterprise credential management documentation describes administrators configuring vendor keys once in the Admin Dashboard, assigning them to workspaces, allowing or forbidding workspace-created credentials, and rotating them centrally. Ask your Dify contact to confirm which of these your license includes, and whether your deployment version exposes them. Community edition is limited to a single workspace and does not provide this model.
Can workspace admins see the provider keys stored in Dify?
Test this directly in your environment, because visibility depends on the role model and on how each credential was created. Log in as a workspace administrator and check whether the provider settings show the full key, a masked value, or only the ability to replace it. Repeat the check for keys assigned centrally from the Enterprise admin area. If workspace admins can reveal keys, treat those keys as shared with everyone who holds that role and plan rotation accordingly. Also confirm how encryption at rest is handled, since the environment reference describes workspace encryption keys stored locally or in Azure Key Vault.
Can I stop workspace users from adding their own provider keys?
Confirm this in the Enterprise credential settings for your version before you write an access policy. The documented Enterprise capability is to allow or forbid workspace-created credentials, which would let a central team own every provider key. In the Community edition, which is limited to one workspace, there is no separate central assignment layer, so the policy has to rest on who holds administrator access and on operating procedure. Ask the vendor how a forbidden workspace behaves for existing apps that already use a workspace-created key.
Does the plugin daemon or sandbox change how stored keys are used?
Confirm this with the vendor and with your own traces, because model calls and plugin execution pass through several services. The Dify 1.16.1 release notes describe token-based authentication between services and agent sandbox network isolation through a Squid proxy, but they do not give enough detail for you to infer where a provider key is read or logged. Check whether keys appear in application logs, worker logs or proxy logs, and test that outbound calls to model endpoints pass through the egress path you intend. Record the result before approving production use.
What does a multi-key design cost, and who pays for the work?
Cost depends on the license edition, the number of provider accounts you must hold, and the internal or partner effort to build and test the key model. Your costs include separate provider contracts or billing projects per environment, the Dify edition you choose, and the time your platform and security teams spend on rotation runbooks and upgrade tests. Dify's pricing page says Enterprise is custom priced, so ask for a written quote tied to your required features, including central credential management and SSO. Ask any implementation partner to separate one-time setup from recurring rotation, testing and support effort.
What to confirm before you assign keys centrally
Before you plan central assignment, confirm that your organization actually runs Dify Enterprise. Central credential management is an Enterprise capability: system administrators configure plugin credentials such as model vendor API keys once in the Admin Dashboard, then assign them to workspaces. The Community edition, which is free and limited to a single workspace according to the Dify pricing page, does not give you that control plane. Ask your Dify account contact to confirm in writing which edition, license and workspace count your quote covers, and confirm that the Enterprise version you deploy includes the credential management features described in the Dify Enterprise documentation.
Next, confirm the provider terms that sit behind each key. A single organization-wide key is only safe to share across environments if your contract with the model vendor allows it, so check data handling, retention and usage terms separately for development and production accounts. Ask your procurement and legal teams to confirm which vendor account, billing entity and spending limit each environment uses, and whether the vendor offers separate projects or keys that map cleanly to your staging and production split. Record the answers before you decide which workspaces may receive which credentials.
Finally, decide how key ownership and rotation will be recorded before the first key is loaded. Name an owner for each credential, the workspaces it is assigned to, the person allowed to change workspace permissions for credentials, and the rotation interval your security policy requires. Confirm whether your team will allow workspace-created credentials at all, since Enterprise lets administrators forbid them. Keep this register outside Dify, in your normal change or secrets system, so that a rotation can be traced without asking the platform. The Dify Enterprise credential management documentation is the next read for the exact admin steps and assignment options.
How DeployOpen scopes and supports Dify provider credentials
DeployOpen works from a written scope and plans the credential layout before any key is entered into Dify. Each card below is one stage of that work, from the key map to documented rotation and optional support after handover.
Written scope before work starts
Every engagement begins with a written scope that names the Dify version, the workspaces in play, the model providers and the environments that need their own keys. The scope states which credentials are in the client's hands and which are configured by DeployOpen. Ask for the scope to list each provider account, who owns it, and which environments it serves, so the quote follows from defined work.
Key map for each environment
Before configuration, DeployOpen drafts a key map that shows which provider account and key serve development, staging and production, and which workspace uses each one. The map records who may rotate each key and where the original secret is stored. Check that every production key is separate from development keys so a test workflow cannot spend production quota.
Workspace and credential configuration
DeployOpen configures workspaces, assigns model provider credentials and sets the rules for who may add new ones. On Dify Enterprise, system administrators can configure vendor API keys once in the Admin Dashboard and assign them to workspaces. Confirm that workspace creators cannot add arbitrary keys if your policy forbids it.
Verification of separation
DeployOpen tests that development and production traffic reach only their intended provider keys. The checks cover model calls from each workspace, the provider usage dashboards at the vendor, and the behavior of apps that reference a removed or disabled key. Ask for the test results in writing so your team can repeat them after each upgrade.
Documented rotation runbook
DeployOpen writes a rotation runbook covering how each key is replaced, which workspaces and apps are affected, and how the old key is revoked at the provider. It also records how the SECRET_KEY and encryption settings are handled, since changing SECRET_KEY after deployment logs out all users. Your team should be able to rotate a key without a consultant present.
Optional retainer for upgrades
Provider credential behavior can change between Dify releases, so DeployOpen offers an optional retainer for upgrade testing and re-verification of the key map. Retainers cover ongoing support rather than the initial build, and their scope is agreed in writing. Ask what the retainer includes for review after each minor release, which arrive roughly monthly.
