API keys

When you create a key in Settings → Connections, we generate a high-entropy random token, hash it, and show the plaintext exactly once in the create dialog.

Static MCP URLs include ?token=smcp_.... The runtime hashes the incoming token, resolves its workspace and access scope, and runs the request inside that tenant boundary. OAuth clients use https://my.shop-mcp.app/api/mcp without a query token; ShopMCP returns the appropriate workspace bearer only after browser consent.

If a client requires a static URL, create one key for that client and name it after its location or purpose. That way you can revoke one machine or automation without breaking other clients. OAuth-capable clients should use their own login flow instead of sharing a copied URL.

To rotate a key:

• Create a new MCP URL with a similar name (e.g. add a date suffix).
• Update the chat client config to use the new URL.
• Restart the client and confirm tools still load.
• Delete the old URL.

We recommend rotating every 90 days for any key that lives on a shared machine. Keys on your personal devices can rotate yearly.

Then check Usage for any tool calls in the window between leak and revocation. If you see anything you don't recognize, email security@shop-mcp.app and we'll help you trace what was accessed.

Every connection to your MCP URL is tracked as a “session”. A session is identified by a stable hash of api_key + IP + user-agent — the same Claude Desktop install on the same network reuses the same session across restarts; a second laptop on the same key shows up as a distinct session.

• Solo: 2 devices (laptop + desktop). A 3rd concurrent device evicts the oldest — the evicted client gets a clear error pointing to an upgrade.
• Brand: 6 devices (3 users × laptop + desktop headroom). Adding a teammate does not create an MCP URL automatically.
• Portfolio: 10 devices per workspace (5 users × 2), shared across every brand workspace on the account.
• Agency: 20 devices per workspace (10 users × 2), shared across all branched client workspaces.
• Agency Scale: device count is contract-driven — your rep sets the cap.

Active devices, including ones pending approval, are listed at Settings → Devices. You can revoke a device there to force it to reconnect.

Solo is a single-user plan, so the first time a new device fingerprint connects we block tools/call until you approve the device in Settings → Devices. The client can still list tools, but running them returns a device_pending_approval error with a link to approve.

Human-device approvals are valid for 30 days — after that, a re-prompt. A verified Google Apps Script project is approved once and stays trusted until you revoke it or rotate its API key; each new script project still needs its own first approval. Brand, Portfolio, Agency, and Agency Scale skip this step (seat-based eviction handles device turnover).

We watch for two patterns and email the workspace owner when either trips:

• Impossible travel: the same key used from two different countries within 24 hours.
• Instance sharing: too many distinct client fingerprints on one key in 7 days. Threshold scales with tier — 2 for Solo, 5 for Brand, 10 for Portfolio, 20 for Agency, and whatever your contract specifies for Agency Scale.

First alert is email-only. A second alert within 30 days evicts every active session (clients must reconnect). A third alert revokes the key entirely and you need to rotate from Settings → Connections. This is the anti-sharing escalation ladder; legitimate single-user usage never reaches level 2.

ShopMCP supports OAuth with PKCE, protected-resource discovery, authorization-server metadata, and dynamic client registration. Existing static URL tokens continue to work. The Claude Directory and Microsoft Copilot flows receive dedicated client-profile keys. Other OAuth clients resolve the owner's workspace primary key or a member's dedicated scoped key, subject to the member's current access.