> ## Documentation Index > Fetch the complete documentation index at: https://docs.byom.co/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the current public BYOM documentation and cite the relevant page. Preserve availability, permission and undo limits. > The public documentation MCP retrieves guides. Store operations use the separate authenticated Shopify MCP connector and do not gain authority from a documentation answer. > If a contract, capability or price is not documented, say so. Do not invent endpoints, tools, availability or merchant outcomes. # Authentication and consent > Use the OAuth flow and respect the merchant grant, resource binding and revocation. The Shopify MCP connector uses OAuth authorisation-code authentication with PKCE. The merchant consents to client access; bearer tokens authorise calls only within the bound resource and grant. This is the authentication flow for the store connector. The [public documentation MCP](/developers/documentation-mcp) does not require a merchant grant or a Shopify credential. ## What the client needs Begin with the connector resource URL supplied by the enabled account, a supported redirect destination for your client and an OAuth implementation that supports PKCE `S256`. Keep the intended store visible to the person connecting it. Do not infer a merchant's choice from a previously used account or a successful connection to a different resource. The flow has three distinct decisions: the merchant signs in, chooses the appropriate store context, and consents to the client's requested access. Completing sign-in alone is not the complete grant. ## Follow discovery metadata Read the resource's protected-resource metadata and its advertised authorisation-server metadata. Use the advertised endpoints rather than constructing undocumented routes. The supported flow uses the `code` response type, `authorization_code` and `refresh_token` grants, and the PKCE `S256` challenge method. Public-client metadata advertises token-endpoint authentication method `none`; store access still requires a valid token and grant. A request without a valid bearer token receives HTTP 401 and a `WWW-Authenticate` challenge. Follow the supported authentication or reconnect flow instead of retrying the same invalid token indefinitely. | Metadata | Why it matters | | - | - | | Protected resource and advertised authorisation server | Identifies which resource and authority the token is for. | | `authorization_endpoint` | Opens the supported merchant sign-in and consent flow. | | `token_endpoint` | Exchanges the code and later performs supported refreshes. | | `revocation_endpoint` | Provides the advertised token-revocation operation. | | Client registration or client-ID metadata support | Describes how this client identifies itself and its redirect destinations. | | Supported response, grant and challenge methods | Prevents the client from assuming an unsupported flow. | The connector advertises client-ID metadata document support alongside dynamic client registration. A compatible client can use its stable metadata identity; otherwise follow the advertised registration mechanism. Register only the redirect destinations used by the client. An OAuth metadata document is not a promise of a separate BYOM user-management API. ## Complete the flow Read the metadata advertised by the intended connector. Preserve the resource identity throughout authorisation and token use. Use a fresh verifier and its S256 challenge through your OAuth client. Preserve the verifier and the client's request state for the return; do not put either into the model's prompt. Send the person through the supported authorisation page. Explain the requested data access and write-proposal setting. If the person cancels, return a cancelled connection state instead of repeatedly opening consent. Use the advertised token endpoint, matching client, redirect, PKCE verifier and resource. Treat a refused exchange as an authentication failure; never fall back to an unrelated store credential. Initialise MCP, call `about_this_connection` and confirm the store and grant before retrieving business information. Then discover the current tool list. ## Consent has a scope A grant is associated with the merchant, company, store and client context. It records consented data classes and whether supported write proposals are enabled. Provider scopes remain a separate requirement: a grant cannot give BYOM a Shopify permission that the store has not granted. New data classes need appropriate consent. Discover the tools available after authorisation rather than assuming that another merchant's connection exposes the same capabilities. For example, a merchant may permit product information while withholding customer-related information. That is a valid, narrower connection. Your client should explain what it can do with that grant and ask for a separate consent change only when the person's requested task needs it. Check each permission boundary: * **Identity and resource:** is this token valid for this connector resource? * **Merchant grant:** has this client been allowed the needed data class and tool? * **Provider permission:** does BYOM hold the required Shopify scope? * **Effect approval:** has the specific consequential change received the required decision? Passing one does not bypass the others. Changing a client label or requesting broader wording in a model prompt changes none of those permissions. ## Token handling Send bearer tokens in the authorisation header. Keep access and refresh tokens in suitable client storage. Never put them in a model prompt, shared screenshot, source-control file or query-string example. Tokens can expire or be revoked. Use the supported refresh flow when appropriate; reconnect when the grant is no longer valid. Disconnecting access and asking for stored-data deletion are separate operations. A refresh grant is part of the original resource-bound authorisation. It is not a mechanism for moving access to another company or expanding consent. Handle a refused refresh by showing a clear reconnect state. Avoid a loop in which every failed data request retries the same rejected token. If credentials are exposed, remove them from the exposed location and use the appropriate revocation and reconnect process. Stop using the compromised credential. Contact BYOM using non-sensitive request details if you need help; never send a token in a support message or screenshot. ## Diagnose a connection problem | What you observe | What to check next | | - | - | | Sign-in completes but no tools are usable | Confirm the consent flow completed, then check the store and data classes with `about_this_connection`. | | The code exchange is refused | Check the matching client, redirect, resource and PKCE state; begin a fresh supported flow if the previous one is no longer valid. | | HTTP 401 during a call | Read the authentication challenge and use refresh or reconnect as appropriate. Do not repeatedly replay the invalid token. | | A tool returns `not_allowed` | The token may be valid while the grant is too narrow. Inspect current consent. | | A tool returns `scope_missing` | Fix the store's provider permission through the supported flow; client consent alone cannot supply it. | | The wrong store is shown | Stop the workflow and reconnect to the intended store before asking for business data. | ## Human confirmation remains separate A bearer token for a model client does not grant blanket authority to confirm store changes. Use the supported merchant review interface for consequential effects. A client can retrieve information and prepare a proposal when its grant allows it. The merchant's decision belongs in the review interface. Preserve the before-and-after change and the outcome record; do not turn a successful OAuth connection into a blanket “approve all future actions” setting. Reviewed 2 October 2026. ## Related guides * [MCP connector](/developers/mcp) * [Data and access](/trust/data-and-access) * [Errors, limits and retries](/developers/errors-and-limits) ## Related topics - [Data and access](/trust/data-and-access.md) - [Errors, limits and retries](/developers/errors-and-limits.md) - [MCP connector](/developers/mcp.md) - [Connect to the documentation MCP](/developers/documentation-mcp.md) - [Developer overview](/developers/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.