How Dify agents read Confluence and work with Jira through tool plugins
A team that wants an agent to look up wiki pages and act on tickets does not need a custom connector to do it. The supported method is the official langgenius Confluence and Jira tool plugins from the Dify Marketplace, which agents or workflow nodes call as tools. This is live tool access at run time: when the agent needs a page or an issue, the plugin queries Atlassian for it, and nothing is copied into a Dify knowledge base. The decision this section helps with is whether the agent should reach into Atlassian on demand, which is the job these plugins do, or whether the content should be indexed for retrieval, which is a separate job covered below.
Credentials are the first design point. Tool plugins that need authentication take workspace-level credentials under Integrations, Tools, then the Tool Plugin, or credentials can be set in a tool's settings inside a specific app or node. Confirm in the plugin's own listing which Atlassian authentication method it expects, which Atlassian site or instance it targets, and which account the token belongs to. The account's permissions set the ceiling on what any agent can read or change, so a dedicated service account scoped to the spaces and projects the agent needs is easier to audit than a personal token. Ask the plugin's maintainers to confirm what each tool operation does before you grant write access.
What you need before connecting Confluence and Jira to Dify
Connecting Confluence and Jira to Dify touches four things: the Dify version and layout you run, the Atlassian identity the plugins authenticate with, the network path from Dify to your Atlassian sites, and the outbound proxy rules that govern those requests. Confirm each one before you install either plugin, because a gap in any of them shows up later as a failed tool call that is hard to trace.
Confirm your Dify version and layout
Start by recording the Dify version, the deployment method and whether you run one workspace or several. The Community edition is limited to a single workspace, so per-workspace credentials matter mainly for Enterprise or multi-workspace layouts. Pick a release from the GitHub releases page and read its upgrade notes first, since minor releases arrive roughly monthly. Plugin behavior can change between versions, so test the tools on the same version you plan to run in production.
Create dedicated Atlassian credentials
Each plugin asks for its own authentication fields. Open the Confluence and Jira listings on the Dify Marketplace and copy the exact field names, then confirm with your Atlassian administrator which account type and token scope each one needs. Create a dedicated service account rather than reusing a personal login, so that access can be reviewed, rotated and removed without affecting staff. Record who owns the account and where the token is stored.
Map the workspace credential location
Tool plugins that need authentication take workspace-level credentials under Integrations, Tools, Tool Plugin, or credentials set in a tool's settings inside an app or node. Decide which location fits each use. Workspace-level credentials are shared by every app in that workspace, while node-level settings limit a credential to one app. Write down which workspace holds the Atlassian credential and who may edit it, because anyone with edit rights can change which Atlassian identity the agent uses.
Verify network reachability to Atlassian
The Dify API and plugin daemon must reach your Atlassian sites over HTTPS. Confirm which Confluence and Jira base URLs the plugins call, including any self-managed or Atlassian Cloud domains, and test the path from the containers that run the plugin daemon, not only from a workstation. Firewalls, DNS rules and TLS inspection proxies often block this path while the browser still works. Note the destination hosts in your change record.
Plan the SSRF proxy path
Dify routes outbound requests through an SSRF proxy, and the SSRF_PROXY settings block internal and private IP ranges. If your Atlassian site resolves to a private address, or your organization sends outbound traffic through a corporate proxy, the request may fail or be filtered. Review these settings with your network team before testing, and confirm the allowed destinations rather than loosening the filter broadly. Keep a record of any exception and its owner.
Set the test and rollback boundary
Before enabling write actions, decide which Jira projects and Confluence spaces the test account may see, and which operations the agent may run. Keep a non-production Dify instance or workspace for trials, and confirm that a backup exists before any upgrade. Ask the plugin's marketplace listing and your Atlassian administrator which permissions the token grants, because the Dify side cannot narrow what the Atlassian account can do.
Configuring the Confluence and Jira tool plugins step by step
This sequence takes a self-hosted Dify instance from an installed plugin to a verified read call against Confluence and Jira, with credentials scoped to one workspace and checked at each stage. Each step ends with a check, so a failure is caught before the tools reach production apps.
Confirm the Dify instance and workspace layout
Before installing anything, the platform owner confirms which Dify instance and workspace will hold the Atlassian credentials, and who has admin rights there. Confirm the version your team runs, since plugin behavior depends on the plugin architecture introduced in 1.0. The check is a written note naming the instance, the workspace, and the admins who can view or change tool credentials. Community edition is limited to a single workspace, so a separate test workspace may not be available without Enterprise.
Install the official Confluence and Jira plugins
A Dify administrator opens the Dify Marketplace, locates the official langgenius Confluence plugin and the official langgenius Jira plugin, and installs each one into the workspace. Install them one at a time so any failure is traceable to one plugin. The check is both plugins listed as installed in the workspace's tool plugin area, with no install errors in the plugin daemon logs.
Create a dedicated Atlassian service account
Your Atlassian administrator creates a service account used only by Dify, rather than a personal user, so the audit trail and offboarding stay clear. Grant it read access only to the Confluence spaces and Jira projects the pilot needs, and document any write permission you decide to grant later. Record which spaces and projects the account can see. The check is an administrator confirming the account can open one named page and one named test issue in a browser, and cannot open a project outside the pilot list.
Generate and enter credentials at workspace level
Create the API credential for the service account in Atlassian, then enter it in Dify under Integrations, Tools, and the Tool Plugin entry for Confluence or Jira. Repeat for the second plugin. Store the credential only in this location, not in app prompts or workflow variables. The check is that each plugin reports its credential as saved and the authorization test in the plugin settings passes without exposing the secret on screen.
Add the tool to one test app or node
Open a single test app or workflow, add the Confluence or Jira tool to a node, and confirm the node uses the workspace credential rather than a separately entered one. Keep the test app private and unpublished. Limit the first version to one read operation per tool so the test isolates the connection. The check is that the node shows the tool as configured and no credential field is editable inside the node.
Run a read call against a known page and issue
Run the test app with a known input: the title or ID of a Confluence page in the pilot space, and the key of a Jira issue in the test project. Compare the returned content with what the service account sees in the browser. The check is a match on title, key, and status, along with the expected content. If the result is empty or permission errors appear, correct the account's scope in Atlassian before going further.
Test a denied request before wider use
Ask the test app for a page or project outside the pilot list. The call should fail or return nothing. This confirms the service account's narrow permissions are enforced, not just documented. Record the result with the test date and the Dify version. The check is a denied response for the out-of-scope item, logged in your change record before any production app receives the tool.
How the agent reads and changes Confluence and Jira
The model chooses a tool, but the plugin does the work. When an agent or workflow node decides it needs Confluence or Jira data, the model emits a tool call naming one of the actions the plugin exposes. The Dify plugin then calls the Atlassian API using the credential stored for that plugin, and the response is returned into the prompt as tool output for the model to reason over. The model never sees the stored token and cannot widen the set of actions beyond what the plugin defines. That means the real boundary is the combination of the plugin's action list and the permissions of the Atlassian account behind the credential, so both need to be reviewed together before anyone writes agent instructions.
Before writing those instructions, open the Confluence and Jira listings on the Dify Marketplace and confirm the supported actions for the exact plugin version you will install. Treat the listing as the starting point for scope, not as a permanent guarantee, because actions can be added or removed between versions. For each action, decide whether the agent should be allowed to call it at all. Read-only lookups of pages or issues are a different risk from actions that create or update issues, comment, or change fields. Any write action the plugin exposes should be matched to an explicit business reason and a test case, and any action you do not need should be left out of the agent's tool selection for that app.
The agent cannot change permissions beyond what the service account already holds. Space permissions, project roles, group membership and workflow rules remain under Atlassian's own administration, and a Dify plugin cannot grant access the account lacks. Use a dedicated service account with the narrowest Confluence space and Jira project access that the use case requires, and confirm with your Atlassian administrator how that account is provisioned, rotated and disabled. Because the credential is held at workspace level or in a tool's settings within an app, anyone who can edit that app or workspace may be able to reuse it, so restrict who holds those roles and test with a second account to confirm the agent sees only what it should.
Which Confluence and Jira fields map to Dify inputs and outputs
This table compares the inputs an agent supplies to the Confluence and Jira tool plugins with the Atlassian objects they refer to and the fields the model receives back. Parameter names are not in the researched facts, so confirm each one against the plugin version you install before you write prompts or workflow nodes. The main takeaway is that the agent sees only what the plugin returns, so the mapping you verify decides what it can answer.
| Atlassian object | Agent input the plugin expects | Returned to the model | Confirm before build |
|---|---|---|---|
| Confluence space | Space identifier or key, if the plugin accepts one | Space name and key on each page result | Whether the plugin lists spaces or needs a known key |
| Confluence page | Page ID or title within a space | Title, body content and page URL, if the plugin returns them | Whether body format is HTML, storage or plain text |
| Confluence search | Text query, optionally scoped to a space | Matching page titles and excerpts | Result count limit and paging behavior |
| Jira project | Project key, such as a short uppercase code | Project name and key on issue results | Whether project lookup is a separate tool call |
| Jira issue | Issue key, such as PROJ-123 | Summary, description, status, assignee and reporter, if exposed | Which fields are returned by default and which need expansion |
| Jira search with JQL | JQL string, only if the plugin exposes a JQL-style filter | Issue keys and summaries for matches | Whether raw JQL is accepted and how invalid queries fail |
| Jira write actions | Issue key plus fields such as summary, comment or status transition | Confirmation or new issue key | Which write operations exist in the installed version at all |
Scoping credentials and limiting what the agent can change
An agent that reads Confluence and changes Jira issues is only as safe as the credentials behind it and the actions it is allowed to take. The cards below cover how to scope identities per workspace, separate read and write capability, keep human approval in the path, and protect the Dify secrets that guard stored Atlassian credentials.
Dedicated service account per workspace
Create a separate Atlassian service account for each Dify workspace instead of reusing a personal login or a shared administrator account. Tool plugins that need authentication take workspace-level credentials under Integrations, Tools, and the same credentials can also be set inside a tool's settings in an app or node, so check where each credential lives before you rotate or revoke it. Confirm that the account can be disabled without touching other workspaces.
Least-privilege project and space permissions
Grant the service account only the Jira projects and Confluence spaces the workflow needs, and nothing at the site administration level. Review whether the account can see restricted pages or issue types that the agent's business purpose never requires. Ask the Atlassian administrator to confirm which permission schemes apply to each project, because a broad group grant can silently expose content to every agent in the workspace.
Read-only agents as the default
Build the first version of each agent so it can search, fetch and summarize Confluence pages and read Jira issues, with no create, update or transition actions enabled. Give write-capable tools to a separate agent or workflow that a named owner approves. Keeping these two roles apart means a prompt injection in a page body cannot quietly turn a summary task into a ticket change.
Human review before write actions
Where the workflow supports a pause for review, place a human approval step before any Jira issue is created, updated or moved to another status. The reviewer should see the exact fields and target project the agent intends to write, not a free-text summary. Confirm with your Dify version which workflow nodes can hold for input, since behavior in each release should be tested rather than assumed.
Protecting SECRET_KEY and stored credentials
The SECRET_KEY variable signs session cookies and JWTs and encrypts OAuth credentials, so treat it as a secret held outside the repository and backed up securely. Changing it after deployment logs out all users, so plan that change for a maintenance window. Workspace encryption keys can be stored locally or in Azure Key Vault, and you should decide which option your security team will operate before Atlassian tokens are entered.
SSRF_PROXY allowlisting for Atlassian hosts
The SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, which protects the platform from reaching internal services through a tool. Confirm that your Atlassian Cloud or self-managed hostnames are reachable through that proxy, and keep the allowlist narrow so it does not open routes to other internal systems. Test the tool from a workflow after every change to the proxy or DNS configuration.
Why indexing Confluence into a knowledge base is a different job
Reading Confluence through the official tool plugin and copying Confluence into a knowledge base are two different jobs, and the choice between them decides who can see what, how fresh the answers are and what you pay in embedding work. A tool call queries the live source when the agent asks for it, using the credentials configured for that workspace, so the answer reflects the page as it stands at that moment and the agent only sees what those credentials allow. A knowledge base works differently. Dify takes a copy of the content, splits it into chunks, converts each chunk into an embedding and stores the result in the vector store. Every later change in Confluence stays invisible until something re-syncs it, and deleted or restricted pages remain in the index until something removes them.
That copy brings three obligations that a tool integration does not. First, permissions must be mapped: a knowledge base has no native concept of the Confluence space or page restriction a chunk came from, so you must decide whether everyone who can open the knowledge base may read all indexed content, and document that decision before indexing. Second, deletion and restriction changes need a defined sync process and an owner. Third, each re-sync can re-embed changed content, so the model provider bill and the indexing time recur with the size of the content and the sync frequency. Confirm these details against the Dify knowledge base documentation for your version before you commit to a design.
Dify also offers two other routes that sit between these extremes: the Dify knowledge sync pipeline for document sources, and the External Knowledge API, which lets Dify query a retrieval service you run. Each route changes access control, freshness and cost in its own way, so the choice belongs in the written scope. Ask your team which pages are restricted, how quickly answers must reflect edits and who will own sync failures. Those answers usually point to the tool plugin for live, permission-bound lookups and to a knowledge route only for content that is curated and approved for broad reuse.
Common Confluence and Jira tool failures and their fixes
This table pairs each common failure in a Dify Confluence or Jira tool integration with its likely cause and a check you can run. Read it in order when an agent call fails, starting with credentials and permissions before looking at network or upgrade causes. The main takeaway is that most failures trace to scope, network path or version drift, and each can be confirmed without changing the agent.
| Failure | Likely cause | Verifiable fix |
|---|---|---|
| Authentication rejected | Expired or revoked API token, or a token issued to a different Atlassian account than the one the workspace expects | Confirm the credential is saved under Integrations, Tools, Tool Plugin for the correct workspace, then test it with a read-only call to a known page or issue |
| Insufficient permissions on a space or project | The service account can log in but lacks view rights on the Confluence space or the Jira project the agent targets | Compare the account's space permissions or project role with the page or issue the call returns as forbidden, and grant read access before retrying |
| Atlassian host unreachable behind the SSRF proxy | Outbound requests to the Atlassian site are blocked by the SSRF proxy, or the proxy resolves the host to an internal address | Check the SSRF proxy configuration in the environment reference and confirm from the Dify API container that the Atlassian hostname resolves and returns a response |
| Plugin version mismatch after a Dify upgrade | The installed Confluence or Jira plugin was built for a different Dify plugin interface than the upgraded platform | Compare the plugin version in the workspace with the Dify version in use, update the plugin, then rerun a test call in a staging instance before production |
| Agent calls a write tool unintentionally | The tool set on the agent or node includes create or update actions, and the prompt does not restrict when they may run | Review the enabled tool list for each app, remove write actions the use case does not need, and test with a prompt that asks for a change to confirm it is refused |
| Credential visible to unintended apps | The credential was entered in a tool's settings inside one app instead of at workspace level, so other apps or editors cannot be audited | Check where each credential is stored and move shared service accounts to workspace-level credentials so access can be reviewed in one place |
Questions buyers ask before connecting Confluence or Jira to Dify
Are the Confluence and Jira tool plugins free to add to Dify?
The Confluence and Jira tool plugins are official langgenius plugins listed on the Dify Marketplace, and the listing is the place to confirm the current licensing and any cost before you install them. Dify's own pricing covers the platform editions, not third-party plugins, so check each listing for its terms. Your Atlassian account and any Atlassian licensing you already hold are separate costs that the plugin does not remove. Ask your partner to confirm these points in writing as part of the scope.
How much effort does connecting Confluence or Jira to Dify take?
The effort depends on how many spaces and projects the agent must reach, how many distinct credentials you need, and how many apps or workflows call the tools. A single read-only space with one service account is a small job. Effort grows with each additional workspace, each Jira project with its own workflow rules, and each app that needs tested prompts and error handling. Testing the agent's answers against real pages and issues usually takes more time than the credential setup itself.
Can an internal team connect Confluence or Jira to Dify without a partner?
Yes, a team with Dify administration experience and access to the Atlassian admin console can install the plugins and configure credentials under Integrations and Tools. The harder parts are scoping the Atlassian account, deciding where credentials live for each workspace, and testing that the agent cannot write where it should not. Teams without someone who has run Dify in production often benefit from a short review of those decisions. Confirm your internal skills against the Dify tools documentation before you decide.
What does the partner need from our team to start?
Expect to provide an Atlassian site, a dedicated service or integration account with the smallest permissions your use case needs, a test space and a test Jira project, and a named owner who can approve the agent's behavior. The partner also needs network routes from the Dify host to your Atlassian site, and outbound access must be allowed through whatever proxy or firewall you run. Ask for this list in the written scope so that no access request appears halfway through the work.
How long does a Confluence or Jira connection take?
The duration depends on scope, so the reliable answer comes from the written plan rather than a general figure. A connection for one read-only Confluence space and one Jira project in a single workspace is the shortest case. Timing extends with more workspaces, more write actions, approval steps, and testing with your own content. Ask the partner to break the timeline into access setup, configuration, testing and handover, and to state which of those depend on your team's response times.
Can the Dify agent be limited to read-only access in Confluence and Jira?
Read-only behavior is mostly set by the Atlassian account, not by Dify. If the credential has only view permissions in the relevant spaces and projects, the agent cannot change pages or issues through that account, regardless of what a prompt asks. Confirm the permission scheme in Atlassian, then test write actions with the tool enabled to verify that they fail. Also review which tool actions each Dify app exposes, since a plugin may offer more operations than a given workflow needs.
Why is indexing Confluence into a knowledge base a different job?
A tool plugin lets an agent fetch specific pages or issues at the moment a question is asked, while a knowledge base copies content into an index that must be chunked, embedded and refreshed. Indexing adds storage, embedding cost, sync schedules and questions about stale or deleted pages. Permissions also need separate handling, because an index can expose content to users who could not open the source page. Plan these as separate work items with their own owners and scope.
How DeployOpen scopes and supports a Dify and Atlassian integration
DeployOpen plans, implements, documents and supports self-hosted Dify inside your own infrastructure, including the Confluence and Jira tool connections described here. Each engagement starts with a written scope that separates agent read access from any write actions, and the work is handed over with the configuration and runbooks your team needs to operate it.
How we scope
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- We list which Confluence spaces and Jira projects the agent may read, and which actions it may take.
- We confirm which Atlassian accounts, credential owners and workspaces each Dify tool connection will use.
How we build
- We install the official langgenius Confluence and Jira tool plugins and configure workspace-level credentials under Integrations and Tools.
- We test each agent with read-only and write-capable tool calls, and confirm the agent cannot reach pages or projects outside the agreed scope.
- We keep Confluence indexing out of the tool setup and scope any knowledge base work as a separate build with its own sources and access rules.
How we hand over
- We document each credential, its owner, its rotation steps and the workspace it belongs to.
- We provide a record of which tool actions each app and node may perform, so reviewers can check the design against it.
- We walk your operators through upgrade steps, including backups before each Dify release and review of new environment variables.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Retainers can cover plugin version changes and periodic review of which Atlassian permissions agents hold.
- Quotes follow from the written scope, so ask for the scope items, testing steps and handover documents that each quote includes.
