Connection Troubleshooting

The most common connection issues, what causes them, and how to fix them.

"401 Unauthorized" Right After Setup with a Correct Token

You are using an integration token, and Magento is rejecting it as a standalone Bearer token. Since Magento 2.4.4 this is the default behavior. Enable:

Stores → Configuration → Services → OAuth → Consumer Settings → Allow OAuth Access Tokens to be used as standalone Bearer tokens → Yes

Then re-test the connection in the app.

"The Store URL Appears to Point at the Magento Admin Panel"

The Store URL field contains your admin URL, for example https://your-store.example/admin_x1y2. That does not work: in Magento, the admin front name owns every path under it, so the app's API requests get the admin login page back instead of API responses. The app detects this and names it in the connection test.

Fix: enter the storefront base URL, the address customers use to shop, without the admin path. A separate admin domain (such as https://admin.your-store.example with no path) is fine; only the admin path breaks API routing.

Admin Login Fails While the Credentials Are Correct

Magento's Magento_TwoFactorAuth module, enabled by default, takes over the admin token endpoint the app uses and answers a plain username-and-password request with "Please use the 2fa provider-specific endpoints to obtain a token." The app recognises that answer and asks for the code from the admin's authenticator app. With Google Authenticator as the store's provider, the sign-in completes with that code.

If no code prompt appears, or the code is refused:

1. Check the store's provider under Stores → Configuration → Security → 2FA → Providers. The app answers Google Authenticator only. Duo Security, Authy and security keys need a browser, so for those accounts use an integration token (how). Integrations are not subject to admin 2FA.
2. The admin has 2FA enabled but never finished setting it up. Magento then sends a setup email instead of accepting a code ("You are required to configure personal Two-Factor Authorization in order to login."). Complete the setup in the Magento admin first.
3. Use OAuth 1.0a, which authenticates with signed requests instead of a login.

We do not recommend disabling 2FA for admin accounts to make admin login work.

"Session Expired" During the Day

Admin-login tokens expire after four hours by default. With stay signed in enabled the app renews the token in the background and retries the request; you will not normally see this. When renewal is not possible (the password changed, or stay signed in is off), the app shows a reconnect prompt: tap Not connected in the header and choose Reconnect, or sign in again.

If this happens often, switch the store to an integration token; those never expire.

The Store Is Unreachable

The header shows a Not connected pill whenever the app cannot reach the store. Tap it to see the reason and retry:

• No network: the device has no internet connection. Sales are kept on the device; see local receipts.
• Store not responding: the server is down or not reachable from this network. Check whether the store loads in Safari on the same device.
• Maintenance mode: Magento answers with a maintenance page. The pill retries as soon as the store is back.

Everything Returns 404

If every request 404s, a reverse proxy or firewall in front of Magento is usually blocking the REST path. Verify that https://your-store.example/rest/V1/ is reachable from the device's network and not stripped by the proxy configuration.

Everything Returns 401

A staging or test environment behind HTTP basic authentication answers every request with a password prompt the app cannot fill in: the wizard's connection test fails, and a connected register shows the store as unreachable. Either exempt Magento's REST API, everything under /rest/, from the basic authentication in the web server configuration, or allow the IP address the devices connect from. The storefront and the admin can stay behind the password.