Authentication errors prevent integrations from connecting to Mintsoft or to third-party platforms. This guide helps you identify the cause of an authentication failure and points you to the right fix. Work through each section in order until the issue is resolved.
Tip: Before starting, check the Connect Overview page in Mintsoft. A red inactive status on a connection confirms an authentication problem. Green means the connection is live and authenticated.
Step 1: Identify the error type
Find the exact error message in Mintsoft. Go to Connect then Order Integrations (or Courier Integrations), locate the affected connection, and click View Errors or check the Import Errors screen.
Match your error to one of the types below, then follow the corresponding section.
Error or symptom | Most likely cause | Go to |
401 Unauthorised | Expired or incorrect credentials, or deprecated API method | Steps 2 and 3 |
403 Forbidden | Account lacks the required permissions for the operation | Step 4 |
Authorisation token is hard expired | OAuth token needs to be renewed (common on eBay) | Step 5 |
Invalid credentials / Authentication failed | Test/production mode mismatch, or credentials entered incorrectly | Step 6 |
Deprecated API authentication method | Integration is using the legacy GET auth method | Step 7 |
Connection inactive, no specific error shown | Credentials may have changed or the connection needs to be re-authorised | Step 2 |
Step 2: Check your credentials are still valid
Credentials can become invalid for several reasons: a password change on the third-party platform, an API key that has been regenerated, or an account that has been deactivated. Before re-entering anything, confirm the following:
Log in to the third-party platform (Shopify, Amazon, eBay, DPD, etc.) directly to confirm the account is still active.
Check that the API key or token in Mintsoft matches what is currently shown in the third-party platform's developer or integration settings.
Look for any emails from the platform about security changes, credential resets, or permission updates.
If the platform uses rotating API keys, check whether the key has been regenerated since the connection was set up.
To update credentials in Mintsoft:
Click Connect then the relevant integration type (for example, Order Integrations or Courier Integrations).
Locate the affected connection and click Edit.
Replace the existing credentials with the current values.
Click Update and check whether the connection status changes to active.
Step 3: Check for leading or trailing spaces in credential fields
Copy-paste errors frequently introduce invisible spaces before or after API keys, tokens, or passwords. These cause authentication to fail even when the credential itself is correct.
To check:
Click into the affected credential field in Mintsoft.
Press Home on your keyboard to go to the start of the value.
Check whether the cursor is positioned before the first visible character (indicating a leading space).
Press End and check for any space after the last character.
Delete any extra spaces, then click Update.
Tip: When copying API keys, copy from the platform's interface rather than from a document or email, where extra formatting characters may have been introduced.
Step 4: Check account permissions (403 Forbidden)
A 403 error means the credentials are valid but the account does not have permission to perform the action. This is different from a 401 (where the credentials are not recognised at all).
Common causes:
The Mintsoft user account does not have the correct Connect role assigned. Go to Settings then Warehouse User Accounts, locate the user, and verify the relevant Connect role group is assigned (for example, Connect-Shopify, Connect-Amazon).
The API key was created under an account with restricted permissions on the third-party platform. Check the API key's permission scopes in the third-party platform's developer settings.
A recent change to the user's role or permissions on either platform has removed access.
Contact your system administrator to review and restore the required permissions if you cannot make these changes yourself.
Step 5: Renew an expired OAuth token
Some integrations use OAuth tokens that expire after a set period and must be manually renewed. eBay is the most common example: when a token expires, orders stop importing and the error 'Authorisation token is hard expired' appears.
To renew the token:
Click Connect then Order Integrations.
Locate the affected connection and click Edit.
Click the Authorise or Re-authorise button.
Follow the prompts to log in to the third-party platform and grant access.
Click Update to save.
Note: OAuth tokens on some platforms (including eBay) have a fixed lifespan and will need to be renewed periodically. If you are seeing token expiry regularly, check whether the platform offers a way to extend token validity or set a reminder to re-authorise before the expiry date.
Step 6: Check test mode and production credential alignment
The most common cause of 'Invalid credentials' or 'Authentication failed' errors is a mismatch between the Test Mode setting and the type of credentials entered. Test credentials will not work in production mode, and production credentials will not work in test mode.
Credentials type | Test mode setting | Result |
Test credentials | Enabled | Connects correctly |
Production credentials | Disabled | Connects correctly |
Test credentials | Disabled | Authentication failure |
Production credentials | Enabled | Authentication failure |
To check and correct the setting:
Click Connect then the relevant integration type.
Locate the connection and click Edit.
Find the Test Mode toggle.
Ensure the toggle matches the type of credentials you are using.
Click Update.
For more detail on how test mode works, see Integrations - Test Mode toggle.
Step 7: Update to the current API authentication method
If you are receiving the error 'The user is using a deprecated API Authentication method', your integration is using the legacy GET-based authentication that was retired on 1 May 2024. All API integrations must now use the POST method with credentials passed in the request body, and the API key passed in the ms-apikey header.
This affects custom or third-party integrations using the Mintsoft public API directly. It does not affect courier developer portal integrations.
Follow the migration steps in API - Authenticate requests to update your integration. If a third-party developer maintains your integration, share that article with them.
Important: If you are using the legacy Mintsoft WMS mobile app, you will also see this error. You need to migrate to the Access Mintsoft app. Contact the Mintsoft support team for guidance.
Still unable to authenticate?
If you have worked through all the steps above and the connection is still failing, contact the Mintsoft support team. Provide the following to help with investigation:
The full error message, including any error codes.
The name of the integration and the platform it connects to.
The date and time the error first occurred.
Screenshots of the error from the Import Errors screen or connection settings.
Confirmation of which steps above you have already tried.