401 Unauthorized

United States

401 (Unauthorized) is an error that can occur for a variety of reasons. Use the following guidelines to troubleshoot 401 error.

Use the right environment

Clover sandbox and production are separate environments. Make sure that you are not mistakenly executing your request in the incorrect environment.

Use the correct URL (link) for your environment

See Sandbox base URLs and Production base URLs for more information.

Ensure your request has no errors

Typing errors in requests often cause a 401.

Ensure that the access token is passed correctly.
The merchant ID required for our REST API is a 13-character alphanumeric ID. Example: TC4DGCJW1K4EW.
To locate your merchant ID:

  1. Log in to the Developer or Merchant Dashboard.
  2. From the left navigation menu, click Setup > Merchants. On the Account Settings page, the ID appears in the Merchant column under the merchant name.

Check your app's permissions

Clover merchant data is protected by a permissions scheme that requires each merchant to approve access. The API does not distinguish between an unauthorized error (401 - expired/invalid token) and a permissions error (403 - token has insufficient privileges -403), and returns a 401 in either case. You need to check the following:

  • Does your application request the correct permissions for the API you are calling?
    Example, if you are attempting to create a new order, but your app does not request the ORDERS_W permission, an error is returned.
  • Was your application configured to request the permissions it requires at the time the application was installed? Merchants need to re-install the application if you have modified the permissions after they installed the application. A new token is also generated using the OAuth flow. This is necessary to protect merchants as they accept the permissions and terms of your application when they install it.

you will need to uninstall and re-install the application and then generate a new access token using the OAuth flow. This is necessary to protect our merchants as they accept the permissions and terms of your application when they install it.

Uninstall an app

  1. Log in to the Developer Dashboard.
  2. From the header, select Your Name > Businesses > Merchant Name.
  3. From the left navigation menu, click More Tools.
    The My Apps page appears.
  4. From the top-right menu, click My Apps.
  5. Find your application in the list; you may need to scroll using the Next button.
  6. For the application, in the Actions column, click the ⋮ icon and click Uninstall app.

Reinstall an app

  1. Log in to the Developer Dashboard.
  2. From Your Apps, select your application, and then click Market Listing.
  3. Click Preview in App Market.
  4. Click Connect, and then accept the terms of your application.

Check your app's configuration

Verify if application's Default OAuth Response is set to Code or Token? This setting is available in the Developer Dashboard under REST Configuration in your application's settings.

  • If your application's OAuth response is set to Code, you must obtain an access token by going through the entireOAuth flow.
  • If it is set to Token, you receive the access token directly in step 2 of the OAuth flow.



Using a token is only allowed when testing in the sandbox.

Follow the OAuth flow correctly

If your application's Default OAuth Response is set to Code, ensure that you have completed all steps of the OAuth flow. The code received in step 2 is not an access token. If you try to pass this code as an access token, you receive a 401 - Unauthorized error.

Authenticate API requests using the Authorization Bearer header

API requests must be authenticated using the Authorization Bearer header. Trying to authenticate the request in any other manner returns a 401 - Unauthorized response. For example, any requests using the access_token query parameter for authentication result in a 401 - Unauthorized response.

Use merchant tokens correctly

Merchant tokens do not support Cross-Origin Resource Sharing (CORS). If you are using a merchant token and making a call directly from a web browser, your request will fail. You either need to proxy Clover API requests through your server or use an OAuth token.