Prepare the admin database
Use Postgres behind Hasura and track the tables created by the selected migration:
The additive migration preserves legacy configuration rows and creates the separate site-config
layout. Track
widget_orgs, widget_admin_keys, widget_sites and the selected config table.
Insert verified organization IDs before issuing keys; migration 005 seeds none. OAuth for the
MCP connector also requires migration 003 and its client/grant tables.
Set WIDGET_ADMIN_GRAPHQL_URL and WIDGET_ADMIN_GRAPHQL_ADMIN_SECRET, or their
STATESET_GRAPHQL_URL/STATESET_GRAPHQL_ENDPOINT and STATESET_GRAPHQL_ADMIN_SECRET
fallbacks. Without configured Hasura, public settings return 204 and admin database operations
cannot succeed. Set PUBLIC_BASE_URL to the external API/assets origin used in install snippets.
WIDGET_ADMIN_ENCRYPTION_KEY is a 64-hex-character key for stored Shopify tokens and stable
OAuth consent signing across replicas.
Bootstrap and scope access
The first key for an existing organization is created withPOST /api/admin/keys and { orgId, label, bootstrapSecret }, where the secret matches
ADMIN_BOOTSTRAP_SECRET. Subsequent keys can be issued with an existing bearer key scoped to
that same org. The plaintext rw_admin_... key is returned once; store it securely and create
one key per operator so claim ownership and revocation remain distinct.
Other admin requests require Authorization: Bearer rw_admin_.... Missing/invalid credentials
return 401 missing_or_invalid_key; a disallowed bootstrap returns 403 forbidden.
Credentials are verified against the admin-key store. These keys never belong in an embed.
Configure, publish and verify
WithWIDGET_ADMIN_KEY already in your environment, run against your own deployment:
GET /api/widget/settings?siteId=... is public and returns { settings }. An explicit site ID without a published config returns
404; an unmatched origin, unavailable admin database, or failed lookup returns 204. It is not protected by an operator key; store only browser-safe
settings there. Generated snippets do not automatically enable the opt-in session issuer;
add data-rw-session-endpoint when that deployment supports it.
Read versions with /config/versions and /config/versions/{version}. Roll back with
POST /config/rollback and { version }, then verify the actual visitor widget.
Snippet detection alone does not establish AI answer quality or a working human handoff.
MCP administration
The same server exposes Streamable HTTP MCP at/mcp. It accepts an OAuth 2.1 access token
(rw_at_...) or a raw admin bearer key; resolved org identity scopes every tool call.
OAuth discovery uses the server’s /.well-known documents. Configure the external
PUBLIC_BASE_URL and database/OAuth migrations before connecting a client.
Tools cover site CRUD, draft/publish/rollback, install generation, install verification,
analytics, organization details and admin-key lifecycle. widget://config-schema exposes the
configuration schema; setup_widget describes the configure/publish/install/verify workflow.
Use discovery against your deployed server for the current tool schemas. Native conversation
claims, replies and private notes use the REST operator routes, rather than these site-admin tools.
For deployment qualification and release evidence, see
Widget deployment.