Skip to content

Connection Troubleshooting

Hyvä POS is in closed beta

Hyvä POS is currently in a closed beta (pilot phase) with a small group of merchants. It is not yet generally available: the App Store release follows the pilot, and features and configuration may still change - possibly in backwards-incompatible ways - before the general release. Want to take part? Sign up at hyva.io/pos.

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

The admin account almost certainly has two-factor authentication enabled, which is the Magento default. The Magento_TwoFactorAuth module takes over the admin token endpoint the app uses and rejects the request even when the password is right, typically with "Please use the 2fa provider-specific endpoints to obtain a token." The app cannot complete a 2FA challenge on that endpoint.

Pick one of these, in order of preference:

  1. Use an integration token instead (how). Integrations are not subject to admin 2FA.
  2. 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.

Test from the device

Most connection problems are network problems. Opening the store URL in Safari on the same iPad tells you in seconds whether the store is reachable, has a valid certificate, and is out of maintenance mode.