> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# SDK authentication: API key and shop token

> How the SDK authenticates: the app API key (mrd_sk_) versus the short-lived shop token (mrd_shop_), token refresh, uninstalls, transport and rate limits.

The SDK talks to Meridian's developer-facing API at `https://api.the-meridian.ai/api/public`. Two credentials cover every call, and which one a call uses is decided by where the code runs, not by what it does.

| Where your code runs | Credential | Built with |
| - | - | - |
| Your server, on behalf of your app | App API key (`mrd_sk_…`) | `createMeridianApp`, `createMeridianAdminClient` |
| Your server, on behalf of one shop | Shop token (`mrd_shop_…`) | `createMeridianServerClient` |
| The merchant's browser | Shop token (`mrd_shop_…`) | `MeridianProvider` |

Both travel as `Authorization: Bearer <token>`.

## The app API key

Your app's secret key identifies the **app**. It is what mints shop tokens in the first place, and it is the only credential that can write across shops, so it never leaves your server. It authenticates:

* `identify`: the handshake that upserts a shop and returns its shop token
* the affiliate referral stash, and the app lifecycle event that fires your install automations
* [custom field values](https://help.the-meridian.ai/custom-fields-api.md) written from your backend
* the webhook topic set the SDK reconciles per shop

Every one of those calls also carries your app ID, which Meridian cross-checks against the key. A valid key presented with someone else's app ID is a `401 INVALID_API_KEY`, not a silent write to the wrong app.

## The shop token

A shop token identifies **one install**: this app on this shop. You mint one server-side with `mintShopToken`, and from then on both your server and that shop's browser use it.

It is scoped and short-lived:

* **Scope**: reads and billing writes for that one shop. It cannot reach another shop's data, cannot call the Shopify Admin API, and is not your API key.
* **Lifetime**: about an hour. The provider refreshes it transparently when it expires, and calls `onTokenRefreshed` so you can persist the new value.

Both properties are what make it safe in the browser. Billing calls run client-side with it, so any script on the page can use it while it is valid, bounded to that one shop's billing. Meridian resolves the Shopify Admin token on its own side, so there is no server bridge to build for subscribe, cancel or track.

If you would rather enforce those writes on your own server anyway, the provider takes [write overrides](https://help.the-meridian.ai/sdk-provider.md#routing-writes-through-your-own-server).

### How a refresh works

An expired token comes back as `401 SHOP_TOKEN_EXPIRED`. The provider rotates it against `POST /auth/refresh` and replays the original call once. The refresh endpoint accepts an expired token, so an idle shop does not need a fresh `identify`.

A refresh **rotates** the token. For one hour, the previous value still answers `SHOP_TOKEN_EXPIRED`, and `POST /auth/refresh` with it returns the current token as it is, without rotating it again. So another process of your server, or a browser that still holds the previous value, refreshes into the same token as everyone else. The same goes for a token that `identify` replaces once it has expired. Only the token just before the current one is kept: an older one, or the previous one past its hour, gets a plain `401` ("Invalid shop token."). While the shop is uninstalled, the previous value answers `SHOP_TOKEN_REVOKED` like the current one.

The provider hands you the new value through `onTokenRefreshed`, and the SDK itself never refreshes a token that is still live, so a copy you persisted or handed to the browser keeps working for its full lifetime.

### After an uninstall

An uninstall revokes the shop's token. While the shop is uninstalled, that token answers `401 SHOP_TOKEN_REVOKED` ("Shop token is no longer valid for this install.") on every call, refresh included. A token Meridian never issued still answers a plain `401` ("Invalid shop token.").

If the shop installs the app again, the revoked token can still be refreshed until its original hour runs out. Calls made with it answer `SHOP_TOKEN_EXPIRED`, so the provider refreshes it like any expired token, and `POST /auth/refresh` returns the install's current token without rotating it. A copy that the new session already holds keeps working. Past that hour the revoked token is refused for good, and a fresh `identify` replaces it. The SDK handles all of this on its own and shows the merchant nothing.

A **stale Shopify token** is a different `401`, `SHOPIFY_ACCESS_TOKEN_STALE`: the merchant has to relaunch the app to re-authorize. See [Errors](https://help.the-meridian.ai/sdk-errors.md).

### Which Meridian API a token belongs to

Treat a shop token as opaque. It starts with `mrd_shop_`. On production nothing follows the prefix but the token's random part. Off production, Meridian adds its platform's marker right after the prefix (`mrd_shop_stg_…` on staging, `dev_` on dev, `loc_` on a local API).

A token works only on the API that minted it. Sent to another Meridian API, a marked token answers `401 SHOP_TOKEN_WRONG_API`, with `details.minted_by` naming the platform that minted it, instead of a plain "Invalid shop token.". That is what happens when a `MeridianProvider` mounted without `baseUrl` calls production with a staging token. See [Errors](https://help.the-meridian.ai/sdk-errors.md#the-shop-token-belongs-to-another-meridian-api).

## Transport safety

The SDK logs one warning per base URL that is neither HTTPS nor localhost, because a bearer token would otherwise be sent in plain text. It does not block the request. The warning is there to tell you the configuration is wrong before you ship it.

## Rate limits

Each store has its own public-API budget for each credential: the calls made with its shop token, and the calls your server makes with the API key for that store:

| Calls | Limit |
| - | - |
| Reads, tracking, identify, custom fields, contact capture | 120 per minute |
| Subscribe, cancel, raise cap, discount validation | 30 per minute |
| Referral capture | 10 per minute per store, 300 per minute per app |

Because the budget belongs to the store, one shop's browser cannot exhaust another shop's budget, and refreshing a token does not reset it. API-key calls that name no store, such as the webhook configuration, share one budget per app. All the reads and tracking of one app also share a ceiling of 6,000 per minute. An address that sends many unknown tokens is refused with a `429` for the rest of the minute. Tokens and keys that worked in the last hour keep working from that address. Exceeding a limit is a `429`; the SDK retries it with backoff on the calls where a retry is safe, and [`createMeridianApp`](https://help.the-meridian.ai/sdk-app) skips further calls locally until the `Retry-After` deadline passes. See [Rate limits](https://help.the-meridian.ai/sdk-errors.md#rate-limits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.