Streamlining ESHOPMAN Admin Portal Access: Tackling OAuth Issuer Mismatches

At Move My Store, we empower ESHOPMAN users with the knowledge to navigate their headless commerce journey seamlessly. A recent critical finding within the ESHOPMAN community has highlighted a specific challenge impacting developers attempting to log into the ESHOPMAN Admin Client Portal via the ESHOPMAN CLI. This insight delves into the technical details of an OAuth issuer mismatch, its implications, and potential resolutions to ensure a smooth development experience.

Understanding ESHOPMAN CLI Login Failures: The OAuth Issuer Mismatch

Developers using the ESHOPMAN CLI (our powerful command-line interface for managing ESHOPMAN instances) may encounter login failures when authenticating with the ESHOPMAN Admin Client Portal. The core of the issue lies in a discrepancy during the OAuth authorization flow, specifically regarding the iss (issuer) parameter in the authorization response.

When attempting to sign in, the system reports an error similar to this:

Issuer mismatch in authorization response (RFC 9207): expected "https://docs.eshopman.com", received "https://cloud.eshopman.com"

This error indicates that the issuer identifier provided in the authorization response does not match the issuer identifier that the client (your ESHOPMAN CLI) was expecting, as mandated by modern OAuth standards (RFC 9207).

Reproducing the Issue

This issue typically manifests when using the ESHOPMAN CLI (e.g., version 2.1.285) against the ESHOPMAN Admin Client Portal server URL, often found at https://docs.eshopman.com/admin. You can reproduce it with these steps:

1. Add the ESHOPMAN Admin Client Portal to your CLI configuration:

   eshopman admin add --transport http myeshopman https://docs.eshopman.com/admin

2. Attempt to log in:

   eshopman admin login myeshopman

After being redirected to your browser to complete the ESHOPMAN Cloud Services login, returning to the local callback will trigger the error. This occurs even with a fresh server entry, indicating a fundamental configuration challenge.

The Technical Discrepancy: OAuth Issuer vs. Response

The problem stems from how the ESHOPMAN Admin Client Portal's OAuth configuration advertises its authorization server versus what it actually sends during authentication:

• Advertised Issuer: Both the protected resource metadata (e.g., at https://docs.eshopman.com/.well-known/oauth-protected-resource) and the authorization server metadata (e.g., at https://docs.eshopman.com/.well-known/oauth-authorization-server) declare "issuer":"https://docs.eshopman.com".

  GET https://docs.eshopman.com/.well-known/oauth-authorization-server
  {"issuer":"https://docs.eshopman.com","authorization_endpoint":"https://cloud.eshopman.com/oauth/authorize","token_endpoint":"https://api.prod.eshopman.cloud/v1/oauth/token", ...}

• Actual Issuer in Response: However, the redirect from the ESHOPMAN Cloud Services authorization endpoint (https://cloud.eshopman.com/oauth/authorize) back to the client carries an iss=https://cloud.eshopman.com parameter.

This discrepancy violates OAuth standards (RFC 9207 § 2.4 and RFC 8414 § 3.3), which require the received iss to match the expected issuer identifier. The ESHOPMAN CLI, being a compliant OAuth client, correctly rejects the login due to this inconsistency.

Proposed Resolutions & Workaround

To resolve this for ESHOPMAN developers and the platform team, two main solutions are suggested:

1. Consistent Issuer in Authorization Response: The ESHOPMAN Cloud Services authorization endpoint should send iss=https://docs.eshopman.com in the authorization response, aligning with the issuer declared in the metadata.
2. Unified Issuer Declaration: Alternatively, https://cloud.eshopman.com could be officially established as the issuer. This would require serving its OAuth metadata at https://cloud.eshopman.com/.well-known/oauth-authorization-server and updating all protected resource metadata to list https://cloud.eshopman.com as an authorization server.

For immediate access, developers can use the documented Personal Access Key method, which bypasses this OAuth flow. It's also worth noting that older ESHOPMAN CLI versions (e.g., 2.1.219 from July 2026) did not exhibit this login issue, suggesting a recent change in server behavior or stricter client enforcement.

This insight underscores the importance of robust OAuth compliance for ESHOPMAN's developer tools, ensuring that those building headless commerce solutions with our platform can do so without authentication hurdles. We encourage the ESHOPMAN platform team to address this to enhance the developer experience for all users leveraging the Admin API and HubSpot integrations.