How to Connect Confluence to Macha (with Token-Expiry Monitoring)

This is a setup guide. By the end you'll have Confluence connected as a working knowledge source, your agents reading from it, and — the part most integrations skip — a token-expiry safety net so the connection doesn't silently die the next time Atlassian rotates your API token. That last bit matters more than it sounds, and there's a real reason it shipped, which I'll get to.

Macha is an AI agent layer that sits on top of the helpdesk you already run (Zendesk, Freshdesk, Gorgias, Front). Confluence isn't a replacement for any of that — it's one of the knowledge and tool connectors your agents draw on. So the flow here is: connect Confluence → it becomes a data source → assign its tools to an agent → the agent uses it on real tickets.

What you get when you connect Confluence

Macha's Confluence connector (shipped April 9, 2026) gives your agents seven tools:

The split is deliberate. The four read tools are how Confluence becomes a knowledge source — agents search and read freely. The three write tools (create, update, comment) are real actions that change your documentation, so every one of them requires confirmation before it runs. An agent can draft a new troubleshooting page from a cluster of tickets, but a human approves it before it lands.

There's also a second thing that happens the moment you connect: Macha auto-creates a data source from Confluence, exactly the way it does for Google Workspace and Notion. You don't have to separately "add a knowledge base" — connecting the tool and creating the searchable source is one step.

Before you start: create an Atlassian API token

Macha authenticates to Confluence with an Atlassian API token (not your password). You create it on Atlassian's side first, then paste it into Macha. Per Atlassian's official docs:

1. Go to id.atlassian.com → Account settings → Security → API tokens (direct link: id.atlassian.com/manage-profile/security/api-tokens).
2. Click Create API token.
3. Give it a descriptive name — Macha — Confluence connector is a good one, so future-you knows what it's for.
4. Choose an expiration date. Atlassian lets you set this anywhere from 1 day up to 365 days. Since December 15, 2024, new tokens default to a one-year expiry — you can't make an Atlassian token live forever anymore.
5. Click Create, then copy the token immediately. Atlassian shows it once and never again; if you lose it you create a new one.

Write down that expiration date. You're going to need it in Macha in a minute, and it's the single most important field for keeping this integration alive. More on why below.

Use a token tied to an account (or, better, a dedicated service account) that has access to the spaces you want your agents to read. The agent inherits that account's permissions — it can only see what the token's owner can see, which is exactly the boundary you want.

Step 1 — Add the Confluence connector in Macha

In the Macha dashboard, open Connectors. You'll see everything you can wire up — your helpdesk, commerce and payments tools, and the knowledge/productivity connectors including Confluence.

Click Confluence and you'll get the connection form. You'll provide:

• Your Atlassian site URL (e.g. your-team.atlassian.net)
• The account email the token belongs to
• The API token you just copied
• The token expiration date you set in Atlassian

Save it, and Macha verifies the credentials against your Confluence instance. Once it connects, the seven tools become available to assign, and your Confluence source is created automatically.

Step 2 — Token-expiry monitoring (the part that saves you a Monday)

This is the feature worth slowing down for, because it solves a problem most teams only discover after it's bitten them.

Atlassian API tokens expire — and as of late 2024 they all do, with a hard one-year ceiling. Worse, there's a real-world wave behind this: every Atlassian token created before December 15, 2024 was force-expired sometime between March 14 and May 12, 2026 (per Atlassian's rollout). A lot of "why did our integration just stop working?" tickets in spring 2026 trace straight back to that. And because Atlassian doesn't expose a clean API to read a token's expiry date — confirmed across the Atlassian developer community — a connected app can't just look it up for you. The token simply starts returning 401 Unauthorized, your agents quietly stop finding answers, and nobody notices until a customer does.

Macha's Confluence connector handles this two ways:

• You tell it the expiry date at connect time (the field in Step 1). Macha then emails you a reminder 30 days before the token expires — enough runway to rotate the token and update the connector before anything breaks.
• If a token expires early or is revoked, the connector auto-deactivates on 401 errors instead of hammering Confluence with failing calls. You get a clean "this needs attention" state rather than a flood of silent failures.

The practical payoff: a Confluence integration that tells you it's about to expire, instead of finding out from a confused customer three weeks after it already did. When the reminder lands, the fix is the same 60-second loop — create a fresh token in Atlassian, paste it in, set the new date.

Watch-out: the 30-day reminder is only as good as the date you enter. If you fat-finger the expiration date, the reminder fires at the wrong time. Copy it straight from the Atlassian token screen, and if you ever rotate the token manually, update the date in Macha at the same time.

Step 3 — Confirm the Confluence data source

Because connecting Confluence auto-creates a source, you don't have to build one by hand. Open Data Sources and you'll see your Confluence source listed alongside any websites, uploaded files, Notion, or Google sources you've added.

This is what makes Confluence a live knowledge source rather than a one-time import: your agents search Confluence through the connector's tools at answer time, so an edit your team makes in Confluence this morning is reflected in agent answers this afternoon. There's no stale snapshot to re-sync.

Step 4 — Give an agent the Confluence tools

A connected source does nothing on its own — you point an agent at it. Open the agent you want to make Confluence-aware (or build a new one), and add the Confluence tools from the tool picker.

For a support agent that answers from documentation, you typically want the read tools — Search Pages, Get Page, List Spaces, Get Page Children. Then a one-line instruction does the rest, for example:

"When a customer asks a technical or how-to question, search Confluence for the relevant page, read it, and draft a grounded reply citing the answer. If you can't find a confident answer, hand off to a human."

Add Create Page or Update Page only when you actually want the agent to write back into Confluence — say, an internal agent that turns a recurring ticket theme into a draft runbook for a human to approve. Remember those writes always pause for confirmation.

If you've already connected Zendesk or Freshdesk, this is where it all comes together: the helpdesk trigger fires on a new ticket, the agent searches Confluence for the answer, and drafts (or sends) the reply in your existing helpdesk — no new tool for your agents to learn.

When not to lean on the Confluence connector

A few honest limits, so you build this with eyes open:

• Permissions are inherited, for better and worse. The agent sees exactly what the token's account can see. Point it at a token with broad admin access and an agent could surface an internal-only page in a customer reply. Scope the token's account to the spaces you actually want reachable.
• Messy Confluence in, messy answers out. If your spaces are full of outdated, contradictory, or half-finished pages, the agent will faithfully retrieve the wrong one. Connecting Confluence is a great forcing function to prune stale docs first.
• Write tools are powerful — keep the confirmation gate. Create/Update/Comment require confirmation by design. Don't go looking for a way to auto-approve documentation edits; the human checkpoint is the safety feature.
• It's a knowledge connector, not a migration. Confluence stays your source of truth. Macha reads it live; it isn't copying your wiki somewhere else.

For a public-facing help center you'd often pair Confluence with other sources — uploaded files, your website, or Notion — and let the agent draw on whichever has the answer. Confluence shines for the internal, operational knowledge that never made it into a public KB.

FAQ

Does connecting Confluence import all my pages into Macha? No. Connecting auto-creates a data source, but your agents search Confluence live through the connector's tools at answer time. Edits in Confluence are reflected immediately — there's no static copy to re-sync.

What permissions does the agent have in Confluence? Whatever the Atlassian account behind the API token has. The agent can only read (and, with confirmation, write) pages that account can access. Use a dedicated or service account scoped to the right spaces.

Can agents edit or create Confluence pages automatically? They can create pages, update pages, and add comments — but every write action requires explicit confirmation before it runs. Read actions (search, get page, list spaces, get children) don't.

What actually happens when my Atlassian token expires? Calls start returning 401 Unauthorized. Macha auto-deactivates the connector on 401s instead of failing silently, and — if you entered the expiry date — it emails you a reminder 30 days before the token is due to expire so you can rotate it in time.

Why does Macha ask me to type in the expiry date? Atlassian doesn't expose a reliable API to read a token's expiration, so Macha can't fetch it automatically. Entering it at connect time is what lets Macha warn you ahead of expiry instead of after.

How is Confluence usage billed? Like every connector, agent actions run on credits — priced per AI action by model, not per ticket. See the pricing page for current plans.

Connect Confluence in a few minutes

Confluence is where your team's real answers live; Macha is how your agents reach them on a live ticket — with a token-expiry net so the connection doesn't quietly break on you. Start a 7-day free trial, no credit card required, open Connectors, and wire up Confluence — or read the Confluence integration page and the docs for the full reference.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.