Authentication

Three credential families are issued to customers. A fourth exists and is internal. It is listed here so you do not go looking for it.

1. OAuth 2.1 with PKCE: the MCP path

The primary way an AI client reaches a store. It is a full authorization flow, not a pasted key:

1. The client discovers the authorization server metadata.
2. The user lands on the consent screen at /oauth/authorize and sees exactly which scopes are being requested.
3. The client exchanges the code, PKCE-bound.
4. The access token is scoped to a single storeId and stored hashed at rest.

Use this whenever the client can negotiate. It is the only path where the user sees and approves the scope list, and the only one where you can later narrow a grant.

In OAuth mode the bearer's account is checked on every call, not just the token. A banned or deleted account's live token stops working.

2. bst_mcp_ — the static MCP bearer

For clients that read a config file and cannot run an OAuth flow.

• Minted per store, from the Shopify Custom App settings.
• Stored as a SHA-256 hash; the plaintext is shown once and never re-derivable.
• Holding the key is the authorization. It is store-scoped, so there is no separate scope negotiation.

The consequence of that last point is the thing to understand: a static key satisfies the relay tool family: the tools that reach Shopify through the bridge. It does not satisfy tools that guard a BoostEcom resource whose permission hangs off an organisation membership, because in static mode there is no identified user to check, and an uncheckable permission must refuse rather than pass. See MCP tools & scopes.

3. bei_ — the Intelligence key

A read-only token for the Intelligence API.

• Carries the scope read:intelligence, and that scope is now enforced, not merely stored.
• The rate ceiling is counted per key, not per IP address.
• Stored as a SHA-256 hash.

Anything other than a bare Bearer bei_<hex> is refused outright rather than downgraded to anonymous.

See Intelligence API.

4. bst_ — internal

Admin-minted tokens carrying roadmap.* permissions, consumed by an internal roadmap MCP server. Not issued to customers. Listed only so that seeing a bst_ prefix in a changelog does not send you hunting for a key you cannot get.

Retired: the sk_ family

If you find a reference to sk_ keys or a REST channel endpoint in an old document, it is gone. Those keys lived in a process-local map, so no request ever carried one across an instance boundary and every gated route answered 401. The family and the /api/channels/api endpoint were removed rather than fixed.

Choosing

| You are building | Use | |---|---| | An MCP client that can do OAuth | OAuth 2.1 PKCE | | An MCP client configured by a file | bst_mcp_ | | A read-only intelligence script | bei_ |