Skip to content

docs(user-guide): document cloud scoped vs classic atlassian token urls - #330

Merged
alezander86 merged 2 commits into
codemie-ai:mainfrom
kostiantyn-pshenychnyi1:docs/EPMCDME-13642-jira-confluence-scoped-token-url
Jul 29, 2026
Merged

docs(user-guide): document cloud scoped vs classic atlassian token urls#330
alezander86 merged 2 commits into
codemie-ai:mainfrom
kostiantyn-pshenychnyi1:docs/EPMCDME-13642-jira-confluence-scoped-token-url

Conversation

@kostiantyn-pshenychnyi1

Copy link
Copy Markdown
Collaborator

Summary

Documents why Atlassian Cloud Jira/Confluence integrations fail when a scoped API token is used with the site URL. Since CodeMie sends requests to exactly the URL provided, the URL must match the token type. This closes the gap that led users to enter https://<domain>.atlassian.net (or .../jira) with a scoped token and get authentication failures.

Ref: EPMCDME-13642

Changes

  • jira.mdx — clarified the URL field for Cloud (classic vs scoped token) and added a warning explaining scoped tokens require the https://api.atlassian.com/ex/jira/<cloud-id> gateway, with cloud-ID lookup via /_edge/tenant_info.
  • confluence.mdx — same clarification for Confluence (https://api.atlassian.com/ex/confluence/<cloud-id>).
  • FAQ — added why-does-my-cloud-jira-or-confluence-integration-fail-with-a-scoped-token.md.
  • Self-hosted (Server/Data Center) guidance left unchanged: scoped tokens are Cloud-only, so those instances always use the site URL.

Testing

  • Tested locally with npm start
  • All pages render correctly
  • Images display properly
  • Internal links work
  • Sidebar navigation works

Quality Checks

  • npm run check passes (typecheck + lint + commitlint)
  • No MDX compilation errors (npm run build succeeds)
  • No raw angle brackets
  • Sidebar references document IDs (no new pages added)
  • Images stored locally next to content
  • Commit messages follow Conventional Commits
  • No secrets or credentials in documentation (verified with Gitleaks — no leaks found)

Clarify the integration URL field for Jira and Confluence Cloud: classic
(unscoped) API tokens use the site URL, while scoped tokens require the
api.atlassian.com gateway URL with the cloud ID. Self-hosted is unaffected
since scoped tokens are Cloud-only. Add a matching FAQ entry.

Ref: EPMCDME-13642

Generated with AI

Co-Authored-By: codemie-ai <codemie.ai@gmail.com>
@kostiantyn-pshenychnyi1 kostiantyn-pshenychnyi1 changed the title docs(user-guide): document Cloud scoped vs classic Atlassian token URLs docs(user-guide): document cloud scoped vs classic atlassian token urls Jul 24, 2026
@kostiantyn-pshenychnyi1
kostiantyn-pshenychnyi1 force-pushed the docs/EPMCDME-13642-jira-confluence-scoped-token-url branch from 257d3d6 to 20594ee Compare July 24, 2026 06:58
@alezander86
alezander86 merged commit a86c610 into codemie-ai:main Jul 29, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants