Seekmodo

Seekmodo developer docs

Reference for the REST shim, MCP JSON-RPC surface, and storefront connectors. Authenticate with HMAC; replay window is 5 minutes.

Tenant settings

Everything in this runbook lives behind admin.seekmodo.com → Settings. Read it once when you provision a tenant; come back when something needs to change. Anything you save propagates to your storefront on the connector's next refresh — usually within five minutes.

Page anatomy

The Settings page is a single scroll with these cards, in order:

  1. Display name — what we render in dashboards and on the public docs page.
  2. API credentials — the HMAC shared secret your connector signs with. Reveal + rotate.
  3. Connector policy — search mode, callback allowlist, indexer cadence.
  4. Connector status — live health snapshot from the gateway.
  5. Environment — the env-var picture your connector reads. Read-only summary; useful for debug.

Sibling pages under Settings in the sidebar:

Display name

The friendly label for your tenant inside admin dashboards, emails, and the AI's tool catalog. Doesn't affect billing, the storefront, or any URL. Safe to change any time — the only cache it touches is your own session.

API credentials

Every authenticated call into the gateway carries an HMAC envelope. Your connector ships with the shared secret out of the box, so most merchants never have to touch this card. You only open it when:

  • A new developer needs the key for a one-off script.
  • You suspect the key leaked and want to rotate it.
  • You're wiring the REST shim into a CI job that lives outside the connector.

Both Reveal and Rotate require multi-factor authentication on your operator account. If MFA isn't enrolled, the buttons grey out with a link to your profile's 2FA page.

Rotation grace window. When you rotate, the gateway holds the old secret for 10 minutes before revoking it. That gives the connector time to pick up the new secret on its next 5-minute config refresh without dropping a single request. Don't let more than 10 minutes elapse between clicking Rotate in admin and pasting the new secret into your connector's .env — after that you'll start seeing 401s until the connector restarts.

For the canonical HMAC request shape, see REST — same envelope, same signature math, regardless of which surface you call.

Connector policy

Four knobs control what your connector does when shoppers search:

  • Search mode. One of off / shadow / active / enforce. Most stores ship in shadow for a week (gateway runs in parallel with native, diff-logged) before flipping to active (gateway is the ranker; native is the fallback). Use off as an emergency revert.
  • Callback allowlist. The list of storefront hosts allowed to call /v1/beacon. Add every public domain you serve from — www.example.com, example.com, plus any dev / staging origin (e.g. new-dev.example.com) that should feed shopper telemetry into your tenant.
  • Indexer cadence. Read-only summary of how often the connector pushes catalog deltas. Default is every 10 minutes plus a nightly full at 02:00 UTC. Change cadence inside the connector's .env, not here.
  • Plan tier. Read-only. Bumps happen from the pricing page at checkout; this card just shows the current tier so you know which limits apply.

Connector status

A live snapshot from the gateway showing:

  • Last index push. Timestamp + doc count. Stale > 1 hour means the connector hasn't reached the gateway recently; check the storefront's scheduler.
  • Index size. Documents currently in your tenant's collection. Compared against your plan tier's indexed_docs ceiling.
  • Circuit breaker. closed / half_open / open. Open means the connector is bypassing the gateway and serving native results — usually transient (gateway 5xx) and self-heals in a minute.

If the card shows Couldn't load tenant config, the gateway is briefly unreachable. The storefront keeps serving off the connector's local 5-minute cache; only the admin surface degrades.

Environment

A read-only printout of the connector-side env vars your gateway thinks are in effect (SEEKMODO_MODE, SEEKMODO_GATEWAY_URL, shared-secret prefix + suffix, etc.). Use this card when a setting you saved here doesn't appear to be reflected on the storefront — the env-var printout pins down whether your connector picked up the change on its last refresh.

Deprovisioning a tenant

Self-service tenant deletion lives in your account portal (not here), under Account → Billing → Cancel. Cancelling immediately stops index ingestion + search billing; your data is retained for 30 days for restore before being GDPR-deleted. If you need a hard delete sooner, contact support.