Skip to main content
The SDK reads its credentials from environment variables on your server. Nothing secret ever reaches the browser. createMeridianApp() reads the app ID, the API key and the API URL itself; you can pass appId, apiKey and baseUrl explicitly instead. The developer database ID is read on every identify call. The webhook secret you pass in yourself, to the verification helpers.

​
Where they come from

The app ID and API key live on the app’s settings page, under Meridian SDK credentials. See App settings. The API key is shown once, when it is created or rotated, and never again.

​
Rotating the API key

  1. Click Rotate on the Meridian SDK card. Meridian mints a new key and keeps the previous one authenticating for 7 days.
  2. Copy the new value into MERIDIAN_API_KEY and redeploy.
  3. Watch last used on the old key. When traffic has moved, revoke it early, or wait for the window to close.
  4. Use Revoke only when a key leaked. That stops authentication immediately and will break any instance still holding the old value.
The webhook signing secret is on the same app, under its webhook configuration. Rotating it keeps the old secret verifying for 24 hours, which is your window to roll out the new value.

​
On Meridian hosting

Meridian injects these variables when you deploy, including into existing apps on their next deploy: The two secrets live in Secret Manager. The Managed by Meridian section of your hosting variables lists them without exposing their values. The dedicated hosting key is separate from the key shown once in Meridian SDK credentials. Creating it leaves your existing keys valid. If you declare MERIDIAN_API_KEY or MERIDIAN_WEBHOOK_SECRET yourself, your value wins. Environment-level declarations take precedence over app-level declarations. Delete your override and redeploy to use the managed value again. Meridian does not replace an invalid or outdated manual override. Rotating the API key in app settings starts the same 7-day overlap window for dashboard and hosting keys. Redeploy each hosted environment before that window closes: its next deploy creates or reuses a new hosting key automatically. After rotating the webhook signing secret, redeploy within its 24-hour grace window. Both rotations raise Changes apply on the next deploy. on the app’s hosted environments until a deploy starts. If you use manual overrides, update those values before redeploying. For local development or an app hosted elsewhere, declare MERIDIAN_APP_ID and the dashboard’s MERIDIAN_API_KEY yourself. Also declare MERIDIAN_WEBHOOK_SECRET if you receive forwarded webhooks. See Environment variables for the full managed set, including Shopify credentials and add-ons.

​
What each credential can do

A shop token is safe to hand to the browser, because its scope stops at one shop. Authentication covers that scope in full.
MERIDIAN_API_KEY must never be imported from the React entry, bundled into your app, or placed in a Shopify theme. It is only readable from @the-meridian/sdk/server, and the admin-only methods are only exposed there for that reason.

​
Pointing at another environment

MERIDIAN_API_URL sets the API root, including any platform path prefix. The SDK appends /api/public itself. Leave it unset for the production default, https://api.the-meridian.ai, when running outside Meridian hosting. To call the Meridian staging platform, use MERIDIAN_API_URL=https://staging.the-meridian.ai/staging, with an app ID and API key from that platform. Keep the /staging prefix and do not append /api/public. These public SDK routes are accessible without the platform’s Google login. On Meridian hosting, the platform injects the correct URL automatically. An app’s staging environment on the production platform still uses the production API. See Environments. The Meridian MCP server at mcp.the-meridian.ai accesses the production platform only. It does not list apps created on the staging platform. The SDK logs one warning per base URL that is neither https nor localhost, because your bearer token would otherwise travel in plain text. It still sends the request; the warning is the signal that your configuration is wrong.

​
Local development

meridian dev exports MERIDIAN_DEV_DATABASE_ID into your process. The SDK reads it on every identify call and tags the install with that managed developer database, so Meridian knows to read the shop’s Shopify session from your developer database rather than a deployed one. Installs made by a locally-run app are also always billed as Shopify test charges. Deployed apps have no such variable, and the tag is cleared.

​
Running without Meridian

Credentials are not the only prerequisite: the billing calls also need the app hosted on Meridian. An app with no MERIDIAN_APP_ID or MERIDIAN_API_KEY still works. createMeridianApp() reports configured: false, mintShopToken returns null, gates read as ungated, and the two page components render a quiet empty state with a console warning naming the likely cause. Nothing crashes and nothing throws, so an environment that has not been given credentials yet is a degraded app, not a broken one.
Last modified on October 7, 2026