Create Insights collection key

Outcome

Create an origin-restricted website collector and receive its key once.

Before you start

• Verify the exact identity, environment and approved organization with topolo whoami before discovering this action.
• Inspect the credential-scoped action and canonical resource discovery. Examples use synthetic resources; replace their handles only with separately verified targets.
• Validate the complete input and review the action plan. Mutation and organization-inventory actions require explicit confirmation; a successful shape check does not prove a runtime grant.
• Select a granted workspace through topolo resources. The CLI/MCP supplies canonical resource headers; workspace identity is not an arbitrary payload field.

Discover the target

topolo whoami --json
topolo apps get topolo-insights --json
topolo actions get app_topolo_insights.collection_sites.create --detail --json
topolo resources topolo-insights --json

Request

POST /api/collection-sites · permission workspace:write · confirmation required.

Inspect schemas and test this action in the signed action console. The complete field schema is also available through CLI/MCP action discovery.

Effects and scope

• Requires workspace admin access and an existing sourceKey in that workspace. A missing source returns source_not_found.
• Allowed origins are exact HTTP(S) origins, normalized and deduplicated. Userinfo, path, query and fragment are refused. Plain HTTP is allowed only for localhost or 127.0.0.1.
• Returns siteKey only in this creation response; listing does not return it. Retain it for the intended website and keep it out of unrelated logs and examples.
• Cookieless mode avoids browser subject/session identifiers. Consent mode requires the browser integration’s consent context; a collection key is not proof that a visitor consented. The public collector endpoint is separate from this signed catalog action.

Interpret the response

• Retain data.id and the one-time data.siteKey; compare source, mode and normalized origins through collection_sites.list.
• A successful key creation proves no installed browser script, visitor collection, consent policy or hosted delivery. The example key’s secret is deliberately zeroed.

Worked requests and responses

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Successful and refused captures below are separate examples. A refused response is a boundary, not a successful task.

workflow · refusal 1 · HTTP 404

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.

Input · payload.json:

{
  "sourceKey": "marketing-site",
  "name": "Unknown source",
  "allowedOrigins": [
    "https://example.com"
  ]
}

CLI:

topolo actions validate app_topolo_insights.collection_sites.create --data @payload.json --json
topolo actions plan app_topolo_insights.collection_sites.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "error": "source_not_found",
  "message": "No source is registered in this workspace yet. Register \"marketing-site\" with sources.create first.",
  "details": {
    "requestedSourceKey": "marketing-site",
    "activeSourceCount": 0,
    "registeredSourceKeys": []
  }
}

HTTP 404. Discover the active source id/key in the selected workspace; organization ids and display names are not source handles.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

workflow · refusal 2 · HTTP 400

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.

Input · payload.json:

{
  "sourceKey": "marketing-site",
  "name": "Invalid path origin",
  "allowedOrigins": [
    "https://example.com/path"
  ]
}

CLI:

topolo actions validate app_topolo_insights.collection_sites.create --data @payload.json --json
topolo actions plan app_topolo_insights.collection_sites.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "error": "invalid_collection_site"
}

HTTP 400. Supply exact permitted origins and a valid mode/name; paths, userinfo, query and fragment are not origins.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

workflow · success 3 · HTTP 201

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. The local-only generated collection secret is replaced by 64 zeroes; this is an intentionally unusable example key. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.

Input · payload.json:

{
  "sourceKey": "marketing-site",
  "name": "Cookieless collector",
  "allowedOrigins": [
    "https://example.com",
    "https://example.com/"
  ],
  "collectionMode": "cookieless"
}

CLI:

topolo actions validate app_topolo_insights.collection_sites.create --data @payload.json --json
topolo actions plan app_topolo_insights.collection_sites.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.collection_sites.create --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_insights.collection_sites.create",
    "input": {
      "sourceKey": "marketing-site",
      "name": "Cookieless collector",
      "allowedOrigins": [
        "https://example.com",
        "https://example.com/"
      ],
      "collectionMode": "cookieless"
    },
    "confirm": true
  }
}

Captured raw Worker result

{
  "data": {
    "id": "63038c5f-1b3f-4bb2-b885-231e6362a465",
    "sourceId": "8e8a04e2-340c-4a28-8286-f94554943c78",
    "sourceKey": "marketing-site",
    "name": "Cookieless collector",
    "allowedOrigins": [
      "https://example.com"
    ],
    "collectionMode": "cookieless",
    "status": "active",
    "createdAt": "2026-10-04T08:52:48.350Z",
    "siteKey": "ins_pub.63038c5f-1b3f-4bb2-b885-231e6362a465.0000000000000000000000000000000000000000000000000000000000000000"
  }
}

HTTP 201. Retain data.id and the one-time data.siteKey; compare source, mode and normalized origins through collection_sites.list. A successful key creation proves no installed browser script, visitor collection, consent policy or hosted delivery. The example key’s secret is deliberately zeroed.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

workflow · success 4 · HTTP 201

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. The local-only generated collection secret is replaced by 64 zeroes; this is an intentionally unusable example key. Selected synthetic workspace: ws_insights_workflow. Fixture handles authorize no live request.

Input · payload.json:

{
  "sourceKey": "marketing-site",
  "name": "Consent collector",
  "allowedOrigins": [
    "http://localhost:5173"
  ]
}

CLI:

topolo actions validate app_topolo_insights.collection_sites.create --data @payload.json --json
topolo actions plan app_topolo_insights.collection_sites.create --data @payload.json --confirm --json
topolo actions call app_topolo_insights.collection_sites.create --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_insights.collection_sites.create",
    "input": {
      "sourceKey": "marketing-site",
      "name": "Consent collector",
      "allowedOrigins": [
        "http://localhost:5173"
      ]
    },
    "confirm": true
  }
}

Captured raw Worker result

{
  "data": {
    "id": "b7ad6707-a022-4ead-b8ec-204081e1dc17",
    "sourceId": "8e8a04e2-340c-4a28-8286-f94554943c78",
    "sourceKey": "marketing-site",
    "name": "Consent collector",
    "allowedOrigins": [
      "http://localhost:5173"
    ],
    "collectionMode": "consent",
    "status": "active",
    "createdAt": "2026-10-04T08:52:48.361Z",
    "siteKey": "ins_pub.b7ad6707-a022-4ead-b8ec-204081e1dc17.0000000000000000000000000000000000000000000000000000000000000000"
  }
}

HTTP 201. Retain data.id and the one-time data.siteKey; compare source, mode and normalized origins through collection_sites.list. A successful key creation proves no installed browser script, visitor collection, consent policy or hosted delivery. The example key’s secret is deliberately zeroed.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

grant-boundaries · refusal 5 · HTTP 403

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_merge. Fixture handles authorize no live request.

Input · payload.json:

{
  "sourceKey": "target-property",
  "name": "Denied collector",
  "allowedOrigins": [
    "https://example.com"
  ]
}

CLI:

topolo actions validate app_topolo_insights.collection_sites.create --data @payload.json --json
topolo actions plan app_topolo_insights.collection_sites.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "error": "This workspace requires admin access",
  "code": "workspace_access_insufficient"
}

HTTP 403. This operation requires admin workspace access in addition to its published permission; read_write is insufficient.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

permission-refusals · refusal 6 · HTTP 403

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested. Selected synthetic workspace: ws_insights_merge. Fixture handles authorize no live request.

Input · payload.json:

{
  "sourceKey": "marketing-site",
  "name": "Marketing site collector",
  "allowedOrigins": [
    "https://example.com",
    "https://www.example.com"
  ],
  "collectionMode": "cookieless"
}

CLI:

topolo actions validate app_topolo_insights.collection_sites.create --data @payload.json --json
topolo actions plan app_topolo_insights.collection_sites.create --data @payload.json --confirm --json

Captured raw Worker result

{
  "success": false,
  "error": {
    "code": "action_permission_required",
    "message": "Action \"collection_sites.create\" requires permission \"workspace:write\".",
    "action": "collection_sites.create"
  }
}

HTTP 403. The credential lacks the declared action permission. Inspect credential-scoped discovery in the same approved context; workspace role does not replace the permission.

CLI/MCP adds its transport envelope; CLI --detail retains the full action result.

Verify the outcome

• Retain data.id and the one-time data.siteKey; compare source, mode and normalized origins through collection_sites.list.
• A successful key creation proves no installed browser script, visitor collection, consent policy or hosted delivery. The example key’s secret is deliberately zeroed.

Errors and recovery

• source_not_found (HTTP 404): Discover the active source id/key in the selected workspace; organization ids and display names are not source handles.
• invalid_collection_site (HTTP 400): Supply exact permitted origins and a valid mode/name; paths, userinfo, query and fragment are not origins.
• This workspace requires admin access (HTTP 403): This operation requires admin workspace access in addition to its published permission; read_write is insufficient.
• action_permission_required (HTTP 403): The credential lacks the declared action permission. Inspect credential-scoped discovery in the same approved context; workspace role does not replace the permission.

Only observed refusals are listed. This does not promise that external dependencies or every invalid payload have been exhaustively exercised.

Recovery boundary

Revoke this exact collector id to stop further use of that key. This does not erase previously collected activity; recreating returns another id and secret.

Related actions

• app_topolo_insights.collection_sites.list: List website collectors without exposing their one-time collection secrets.
• app_topolo_insights.collection_sites.revoke: Permanently revoke one selected workspace collector.

Evidence and limits

Actual exported Insights worker, all nine migrated D1 scripts and isolated local R2. Auth identity/grants/archive transport, queue delivery and Analytics Engine sink are synthetic; local queue processing is called explicitly. Notify and Nexus are disabled. No live website, provider, paid usage or deployed data erasure is tested.