Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(docs): enforce dashboard go-link paths and ban app/platform hosts

Sarah Simionescu5ef15774e6cc
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 825e2d315..cc5fe6c42 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -39,4 +39,4 @@ bun run generate:api-index
- API reference pages and toolkit/meta-tool data are generated. Do not hand-edit generated data unless the local generator owns it.
- Changelog entries require `title` and `date` frontmatter, and dates use `YYYY-MM-DD`.
- Prefer cURL for API interactions because docs are consumed by humans and AI crawlers.
-- Links to `dashboard.composio.dev` must carry `utm_source=docs`, `utm_medium`, and `utm_campaign` (content links use `utm_medium=content` and `utm_campaign=<page-slug>`). ESLint enforces TS/TSX; `tests/static/utm-links.test.ts` enforces MDX.
+- Links to `dashboard.composio.dev` must carry `utm_source=docs`, `utm_medium`, and `utm_campaign` (content links use `utm_medium=content` and `utm_campaign=<page-slug>`), and any link with a path must be a go-link (`/~/project/...` or `/~/org/...`) or `/login`. Never link `app.composio.dev` or `platform.composio.dev`. ESLint enforces TS/TSX; `tests/static/dashboard-links.test.ts` enforces MDX.
diff --git a/docs/content/changelog/01-08-26-mcp-api-key-enforcement.mdx b/docs/content/changelog/01-08-26-mcp-api-key-enforcement.mdx
index b72ce186e..1c538ef1c 100644
--- a/docs/content/changelog/01-08-26-mcp-api-key-enforcement.mdx
+++ b/docs/content/changelog/01-08-26-mcp-api-key-enforcement.mdx
@@ -54,7 +54,7 @@ curl -X POST "https://mcp.composio.dev/{your_mcp_server_url}" \
### Via Dashboard
-1. Navigate to [Project Settings](https://dashboard.composio.dev/{workspace}/{project}/settings?utm_source=docs&utm_medium=content&utm_campaign=changelog-01-08-26-mcp-api-key-enforcement)
+1. Navigate to [Project Settings](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs&utm_medium=content&utm_campaign=changelog-01-08-26-mcp-api-key-enforcement)
2. Go to the **Project Configuration** tab
3. Find the **"Require API Key for MCP"** toggle
4. Enable the toggle
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdx
index 6ea0f8f45..630233d92 100644
--- a/docs/content/docs/quickstart.mdx
+++ b/docs/content/docs/quickstart.mdx
@@ -39,7 +39,7 @@ The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `impor
<StepTitle>Configure API Keys</StepTitle>
<Callout type="info">
-Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/settings) and `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
+Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
</Callout>
```bash title=".env"
@@ -185,7 +185,7 @@ readline.close();
<StepTitle>Configure API Keys</StepTitle>
<Callout type="info">
-Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/settings) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
+Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
</Callout>
```bash title=".env"
@@ -348,7 +348,7 @@ readline.close();
<StepTitle>Configure API Keys</StepTitle>
<Callout type="info">
-Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/settings) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
+Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
</Callout>
```bash title=".env"
diff --git a/docs/eslint.config.mjs b/docs/eslint.config.mjs
index 7a5143996..6df1eb4e8 100644
--- a/docs/eslint.config.mjs
+++ b/docs/eslint.config.mjs
@@ -1,8 +1,13 @@
import { defineConfig, globalIgnores } from 'eslint/config';
import nextVitals from 'eslint-config-next/core-web-vitals';
+// Messages must not contain the literal hostnames or they trip their own selectors.
const utmMessage =
- 'Links to the Composio dashboard must carry utm_source=docs plus utm_medium and utm_campaign so sign-ups can be attributed to docs (MDX links are checked by tests/static/utm-links.test.ts).';
+ 'Links to the Composio dashboard must carry utm_source=docs plus utm_medium and utm_campaign so sign-ups can be attributed to docs (MDX links are checked by tests/static/dashboard-links.test.ts).';
+const bannedHostMessage =
+ 'The app/platform composio hosts do not exist; link to the Composio dashboard with a go-link path instead.';
+const goLinkMessage =
+ 'Composio dashboard links with a path must be go-links (/~/project/... or /~/org/...) or /login so they resolve inside the user workspace.';
const eslintConfig = defineConfig([
...nextVitals,
@@ -25,6 +30,26 @@ const eslintConfig = defineConfig([
'TemplateElement[value.raw=/dashboard\\.composio\\.dev/]:not([value.raw=/utm_source=/])',
message: utmMessage,
},
+ {
+ selector:
+ 'Literal[value=/(?<![a-z0-9-])(app|platform)\\.composio\\.dev/]',
+ message: bannedHostMessage,
+ },
+ {
+ selector:
+ 'TemplateElement[value.raw=/(?<![a-z0-9-])(app|platform)\\.composio\\.dev/]',
+ message: bannedHostMessage,
+ },
+ {
+ selector:
+ 'Literal[value=/dashboard\\.composio\\.dev\\u002F(?!~\\u002F(project|org)([\\u002F?#]|$)|login([\\u002F?#]|$))/]',
+ message: goLinkMessage,
+ },
+ {
+ selector:
+ 'TemplateElement[value.raw=/dashboard\\.composio\\.dev\\u002F(?!~\\u002F(project|org)([\\u002F?#]|$)|login([\\u002F?#]|$))/]',
+ message: goLinkMessage,
+ },
],
},
},
diff --git a/docs/tests/static/dashboard-links.test.ts b/docs/tests/static/dashboard-links.test.ts
new file mode 100644
index 000000000..079d41dbb
--- /dev/null
+++ b/docs/tests/static/dashboard-links.test.ts
@@ -0,0 +1,128 @@
+/**
+ * Dashboard link policy tests.
+ *
+ * Authored content must follow three rules for Composio dashboard links:
+ * 1. No app.composio.dev or platform.composio.dev hosts anywhere.
+ * 2. Every dashboard.composio.dev link carries utm_source, utm_medium, and
+ * utm_campaign so sign-ups can be attributed to docs.
+ * 3. Any dashboard.composio.dev link with a path must be a go-link
+ * (/~/project/... or /~/org/...) or /login, so it resolves to the right
+ * page inside the user's workspace.
+ *
+ * Code fences and inline mentions are exempt from rules 2-3; rule 1 applies
+ * to all file content. content/reference is generated upstream and excluded.
+ * TS/TSX is enforced by the no-restricted-syntax rules in eslint.config.mjs.
+ */
+import { describe, test, expect } from "bun:test";
+import { readdir, readFile } from "fs/promises";
+import { join, relative } from "path";
+
+const CONTENT_DIRS = ["docs", "examples", "changelog"].map((dir) =>
+ join(import.meta.dir, "../../content", dir),
+);
+const CONTENT_ROOT = join(import.meta.dir, "../../content");
+
+const DASHBOARD_LINK_RE = /\]\((https:\/\/dashboard\.composio\.dev[^)\s]*)\)/g;
+const BANNED_HOST_RE = /(?<![a-z0-9-])(?:app|platform)\.composio\.dev/;
+const GO_LINK_PATH_RE = /^\/(?:~\/(?:project|org)(?:[/?#]|$)|login(?:[/?#]|$))/;
+const REQUIRED_PARAMS = ["utm_source=", "utm_medium=", "utm_campaign="];
+
+async function findMdxFiles(dir: string): Promise<string[]> {
+ const results: string[] = [];
+ let entries;
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return results;
+ }
+
+ for (const entry of entries) {
+ const fullPath = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ results.push(...(await findMdxFiles(fullPath)));
+ } else if (entry.name.endsWith(".mdx")) {
+ results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+function dashboardLinks(content: string): { line: number; url: string }[] {
+ const links: { line: number; url: string }[] = [];
+ let inFence = false;
+ content.split("\n").forEach((line, index) => {
+ if (/^\s*(```|~~~)/.test(line)) {
+ inFence = !inFence;
+ return;
+ }
+ if (inFence) return;
+ for (const match of line.matchAll(DASHBOARD_LINK_RE)) {
+ links.push({ line: index + 1, url: match[1] });
+ }
+ });
+ return links;
+}
+
+async function collectViolations(
+ check: (content: string) => { line: number; url: string }[],
+): Promise<string[]> {
+ const violations: string[] = [];
+ for (const dir of CONTENT_DIRS) {
+ for (const file of await findMdxFiles(dir)) {
+ const content = await readFile(file, "utf-8");
+ for (const violation of check(content)) {
+ violations.push(
+ `${relative(CONTENT_ROOT, file)}:${violation.line} ${violation.url}`,
+ );
+ }
+ }
+ }
+ return violations;
+}
+
+describe("Content - dashboard link policy", () => {
+ test("no app/platform composio hosts anywhere", async () => {
+ const banned = await collectViolations((content) => {
+ const violations: { line: number; url: string }[] = [];
+ content.split("\n").forEach((line, index) => {
+ const match = line.match(BANNED_HOST_RE);
+ if (match) violations.push({ line: index + 1, url: match[0] });
+ });
+ return violations;
+ });
+
+ expect(
+ banned,
+ `banned hosts found (use dashboard go-links instead):\n${banned.join("\n")}`,
+ ).toEqual([]);
+ });
+
+ test("all dashboard links carry utm params", async () => {
+ const untagged = await collectViolations((content) =>
+ dashboardLinks(content).filter(
+ ({ url }) => !REQUIRED_PARAMS.every((param) => url.includes(param)),
+ ),
+ );
+
+ expect(
+ untagged,
+ `dashboard links missing utm_source=/utm_medium=/utm_campaign=:\n${untagged.join("\n")}`,
+ ).toEqual([]);
+ });
+
+ test("all dashboard links with a path are go-links or /login", async () => {
+ const invalid = await collectViolations((content) =>
+ dashboardLinks(content).filter(({ url }) => {
+ const path = url
+ .replace(/^https:\/\/dashboard\.composio\.dev/, "")
+ .split("?")[0];
+ return path !== "" && path !== "/" && !GO_LINK_PATH_RE.test(path);
+ }),
+ );
+
+ expect(
+ invalid,
+ `dashboard links must use /~/project/..., /~/org/..., or /login paths:\n${invalid.join("\n")}`,
+ ).toEqual([]);
+ });
+});
diff --git a/docs/tests/static/utm-links.test.ts b/docs/tests/static/utm-links.test.ts
deleted file mode 100644
index ca27aafaf..000000000
--- a/docs/tests/static/utm-links.test.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-/**
- * UTM attribution tests.
- *
- * Every markdown link to dashboard.composio.dev in authored content must carry
- * utm_source, utm_medium, and utm_campaign so sign-ups can be attributed to
- * docs. Code fences and inline mentions are exempt; content/reference is
- * generated upstream and excluded. TS/TSX links are enforced by the
- * no-restricted-syntax rule in eslint.config.mjs.
- */
-import { describe, test, expect } from "bun:test";
-import { readdir, readFile } from "fs/promises";
-import { join, relative } from "path";
-
-const CONTENT_DIRS = ["docs", "examples", "changelog"].map((dir) =>
- join(import.meta.dir, "../../content", dir),
-);
-const CONTENT_ROOT = join(import.meta.dir, "../../content");
-
-const DASHBOARD_LINK_RE = /\]\((https:\/\/dashboard\.composio\.dev[^)\s]*)\)/g;
-const REQUIRED_PARAMS = ["utm_source=", "utm_medium=", "utm_campaign="];
-
-async function findMdxFiles(dir: string): Promise<string[]> {
- const results: string[] = [];
- let entries;
- try {
- entries = await readdir(dir, { withFileTypes: true });
- } catch {
- return results;
- }
-
- for (const entry of entries) {
- const fullPath = join(dir, entry.name);
- if (entry.isDirectory()) {
- results.push(...(await findMdxFiles(fullPath)));
- } else if (entry.name.endsWith(".mdx")) {
- results.push(fullPath);
- }
- }
- return results;
-}
-
-function findUntaggedLinks(content: string): { line: number; url: string }[] {
- const violations: { line: number; url: string }[] = [];
- let inFence = false;
- content.split("\n").forEach((line, index) => {
- if (/^\s*(```|~~~)/.test(line)) {
- inFence = !inFence;
- return;
- }
- if (inFence) return;
- for (const match of line.matchAll(DASHBOARD_LINK_RE)) {
- const url = match[1];
- if (!REQUIRED_PARAMS.every((param) => url.includes(param))) {
- violations.push({ line: index + 1, url });
- }
- }
- });
- return violations;
-}
-
-describe("Content - dashboard link UTM attribution", () => {
- test("all dashboard links carry utm params", async () => {
- const untagged: string[] = [];
-
- for (const dir of CONTENT_DIRS) {
- for (const file of await findMdxFiles(dir)) {
- const content = await readFile(file, "utf-8");
- for (const violation of findUntaggedLinks(content)) {
- untagged.push(
- `${relative(CONTENT_ROOT, file)}:${violation.line} ${violation.url}`,
- );
- }
- }
- }
-
- expect(
- untagged,
- `dashboard links missing utm_source=/utm_medium=/utm_campaign=:\n${untagged.join("\n")}`,
- ).toEqual([]);
- });
-});