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

docs/user-guide/tools_integrations/tools/confluence.mdx

@@ -79,15 +79,25 @@ You won't be able to see your token once you leave this screen. Make sure to cop
 - **Global Integration**: Toggle on to use across multiple projects. If disabled, the integration will only be available within the selected project, and assistants and workflows attached to other projects will not be able to use it.
 - **Credential Type**: Confluence
 - **Alias**: Enter integration name (e.g., "codemie-demo").
-- **URL**: Your Confluence instance URL:
-  - For Confluence Cloud: `https://your-domain.atlassian.net`
-  - For Confluence Self-hosted: your own Confluence server URL (e.g., `https://confluence.example.com`)
+- **URL**: The Confluence instance URL. For Confluence Cloud, the correct value depends on the API token type (see the warning below):
+  - For Confluence Cloud with a **classic (unscoped)** token: `https://your-domain.atlassian.net`
+  - For Confluence Cloud with a **scoped** token: `https://api.atlassian.com/ex/confluence/your-cloud-id`
+  - For Confluence Self-hosted: the Confluence server URL (e.g., `https://confluence.example.com`)
 - **Is Confluence Cloud**:
   - ✅ **Check this box** if you're using **Confluence Cloud**
   - ❌ **Leave unchecked** if you're using **Confluence Self-hosted**
 - **Username/email for Confluence**: Your Atlassian account email (e.g., `user@example.com`).
 - **Token/ApiKey**: Paste the API token copied in step 1.4.
 
+:::warning Cloud URL depends on the API token type
+Atlassian Cloud offers two kinds of API tokens, and each one requires a different **URL** value. CodeMie sends requests to exactly the URL provided, so the URL and token type must match:
+
+- A **classic (unscoped)** token works with the site URL: `https://your-domain.atlassian.net`.
+- A **scoped** token (created with specific permissions) only works through the Atlassian API gateway: `https://api.atlassian.com/ex/confluence/your-cloud-id`.
+
+To find the cloud ID, open `https://your-domain.atlassian.net/_edge/tenant_info` in a browser while signed in to Atlassian. The returned `cloudId` value is the `your-cloud-id` used in the gateway URL.
+:::
+
 ![CodeMie Confluence integration form](./images/confluence-codemie-integration.png)
 
 :::tip

docs/user-guide/tools_integrations/tools/jira.mdx

@@ -88,15 +88,25 @@ API tokens should be treated as passwords. Keep them secure and never share them
 - **Global Integration**: Toggle on if you want to use this integration across multiple projects.
 - **Credential Type**: Select **Jira** from the dropdown.
 - **Alias**: Alias is a representation of the integration (e.g., `jira-example`).
-- **URL**: Your Jira instance URL:
-  - For Jira Cloud: `https://<your-domain>.atlassian.net`
+- **URL**: The Jira instance URL. For Jira Cloud, the correct value depends on the API token type (see the warning below):
+  - For Jira Cloud with a **classic (unscoped)** token: `https://<your-domain>.atlassian.net`
+  - For Jira Cloud with a **scoped** token: `https://api.atlassian.com/ex/jira/<your-cloud-id>`
   - For Jira Self-hosted: `https://<your-jira-server-url>`
 - **Is Jira Cloud**:
   - ✅ **Check this box** if you're using **Jira Cloud**
   - ❌ **Leave unchecked** if you're using **Jira Self-hosted** (self-hosted Jira)
 - **Username/email for Jira**: Your Atlassian account email (e.g., `user@example.com`).
 - **Token**: Paste the API token created in step 1.
 
+:::warning Cloud URL depends on the API token type
+Atlassian Cloud offers two kinds of API tokens, and each one requires a different **URL** value. CodeMie sends requests to exactly the URL provided, so the URL and token type must match:
+
+- A **classic (unscoped)** token works with the site URL: `https://<your-domain>.atlassian.net`.
+- A **scoped** token (created with specific permissions) only works through the Atlassian API gateway: `https://api.atlassian.com/ex/jira/<your-cloud-id>`.
+
+To find the cloud ID, open `https://<your-domain>.atlassian.net/_edge/tenant_info` in a browser while signed in to Atlassian. The returned `cloudId` value is the `<your-cloud-id>` used in the gateway URL.
+:::
+
 ![Jira Integration Form](./images/jira-integration-form.png)
 
 2.4. (Optional) Click **Test** button to verify the connection. You should see "Integration test successful" notification.

faq/why-does-my-cloud-jira-or-confluence-integration-fail-with-a-scoped-token.md

@@ -0,0 +1,13 @@
+# Why does my Cloud Jira or Confluence integration fail with a scoped Atlassian API token?
+
+Scoped (granular) API tokens are a Cloud-only feature. Atlassian Cloud offers two kinds of API tokens, and each one requires a different **URL** value in the CodeMie integration. CodeMie sends requests to exactly the URL provided, so the URL and the token type must match.
+
+- **Classic (unscoped)** token: use the site URL `https://<your-domain>.atlassian.net`.
+- **Scoped** token (created with specific permissions): use the Atlassian API gateway URL — `https://api.atlassian.com/ex/jira/<your-cloud-id>` for Jira or `https://api.atlassian.com/ex/confluence/<your-cloud-id>` for Confluence.
+
+To find the cloud ID, open `https://<your-domain>.atlassian.net/_edge/tenant_info` in a browser while signed in to Atlassian and copy the returned `cloudId` value. Self-hosted (Server/Data Center) instances do not use scoped tokens or the gateway URL — they always use the site URL with a personal access token.
+
+## Sources
+
+- [Jira](https://docs.codemie.ai/user-guide/tools_integrations/tools/jira)
+- [Confluence](https://docs.codemie.ai/user-guide/tools_integrations/tools/confluence)