Skip to main content

Session Binding

One folder per project. One spideriq.json per folder. No crossed wires.

The problem​

If you're running an AI agent across multiple client projects — SMS Chemicals in one window, DanMagi in another, VayaPin in a third — token scope alone is not enough to prevent cross-tenant writes. An agent with a PAT scoped to SMS Chemicals could be instructed (or confused) into calling an endpoint with DanMagi's URL parameters. Worse: a developer could publish a page from the wrong repo because the shell happens to be in the wrong directory.

Phase 11+12 of the SpiderIQ platform closes this with Lock 3 — session binding. Every dashboard-scoped CLI or MCP call carries the bound project ID in the URL path (/api/v1/dashboard/projects/{project_id}/content/...), and the backend enforces that the caller's PAT, the URL's project, and the resource being touched all agree (Locks 1↔2↔5).

The binding itself lives in a plain JSON file at the root of your project, the same way .vercel/project.json works for Vercel.

The spideriq.json file​

{
  "project_id": "cli_ov5fdhwseewjf4y9",
  "project_name": "SMS Chemicals",
  "api_url": "https://spideriq.ai",
  "created_at": "2026-04-14T12:34:56.000Z"
}

Commit this file to your repo. Collaborators (human or agent) who clone the repo inherit the same binding automatically. It's not secret — it's the project name in URL form.

Creating a session​

Run once from the repo root:

spideriq use sms-chemicals
# or
spideriq use cli_ov5fdhwseewjf4y9

The CLI resolves the argument against GET /api/v1/auth/workspaces (the list of projects your PAT can access), writes spideriq.json, and prints:

✓ Linked to SMS Chemicals (cli_ov5fdhwseewjf4y9)
  Written to /Users/you/work/sms-chemicals-site/spideriq.json

All dashboard calls from this directory now use /dashboard/projects/cli_ov5fdhwseewjf4y9/… URLs (Phase 11+12 Lock 3).

List what's accessible first:

spideriq use --list

How the binding fires​

Every CLI command that hits a dashboard endpoint — and every MCP tool that wraps one — calls loadProjectConfig(process.cwd()) before making the HTTP request. That walks up from the current directory looking for spideriq.json, stopping at $HOME or the filesystem root.

When found, the HTTP client rewrites:

/api/v1/dashboard/content/pages           # legacy, still works, stamped Deprecated
    ↓
/api/v1/dashboard/projects/cli_ov5fd…/content/pages   # Phase 11+12 scoped

The server extracts {project_id} from the path and enforces Lock 1↔2: the caller's token-scoped client_id must match. Any mismatch returns 403 Forbidden and writes an audit row to content_tenant_audit.

Two sessions in parallel​

The whole point: you can have two agents running side-by-side against different projects without a single cross-wire.

~/work/sms-chemicals-site/spideriq.json   → cli_ov5fdhwseewjf4y9
~/work/danmagi-site/spideriq.json         → cli_jih938kw2ubuij6b

In Antigravity (or any AI agent IDE) Window 1:

cd ~/work/sms-chemicals-site
# agent publishes a page → hits /dashboard/projects/cli_ov5fd.../content/pages/...

In Window 2, simultaneously:

cd ~/work/danmagi-site
# agent publishes a page → hits /dashboard/projects/cli_jih9.../content/pages/...

Neither agent can touch the other's project. If either one is tricked into passing a wrong project_id, the backend 403s before any UPDATE runs. The spideriq.json is the source of truth — the agent doesn't choose, the filesystem does.

Inspecting the session​

spideriq whoami

Shows both the PAT scope and the session binding:

Current Authentication:
  Client ID: cli_ov5fdhwseewjf4y9
  Company: SMS Chemicals
  Email: admin@sms-chemicals.com
  Scopes: content:write, jobs:submit

Session Binding (Phase 11+12 Lock 3):
  Project: cli_ov5fdhwseewjf4y9 (SMS Chemicals)
  Source:  /Users/you/work/sms-chemicals-site/spideriq.json

If the token and the session point at different projects, whoami flags it:

  ⚠ Token is scoped to cli_ov5fd… but spideriq.json points at cli_jih93…
    — calls will 403.

MCP agents​

For MCP (Claude Code, Cursor, Windsurf), the same loadProjectConfig runs on every tool invocation. Start the IDE from the project root; every dashboard MCP tool auto-scopes. No .mcp.json change needed — just commit spideriq.json alongside it.

Edge cases​

  • No spideriq.json anywhere. CLI/MCP fall back to legacy unscoped URLs. You'll see a one-line stderr warning reminding you to run spideriq use PROJECT. The response will also carry Deprecation: true + Sunset: Wed, 14 May 2026 headers.
  • spideriq.json in a parent directory. Found via walk-up. Works from any nested subdirectory (like git does with .git).
  • Suppress the unscoped warning (CI). export SPIDERIQ_SUPPRESS_UNSCOPED_WARNING=1.

See also​