401 Unauthorized

401 (Unauthorized) errors are fairly common and can occur for a variety of reasons. This article discusses ways to troubleshoot a 401 (unauthorized) error.

Use the right environment

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

Use the correct URL for your environment

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

Ensure your request has no errors

Any typos in your request may potentially cause a 401:

  1. Ensure that the access token is being passed correctly.
  2. Make sure that your merchant ID is correct. The merchant ID required for our REST API is a 13-character alphanumeric ID (for example: TC4DGCJW1K4EW). The merchant ID can be found by logging on to your merchant dashboard and selecting Setup > Merchants. The merchant ID is the alphanumeric string under your merchant name in the Merchant column.

Check your app's permissions

Clover merchant data is protected by a permissions scheme which requires each merchant to approve access. In general our API does not distinguish between an unauthorized error (401 - expired/invalid token, etc.) and a permissions error (token has insufficient privileges - should be a 403), and will return a 401 in either case.

  1. Does your application request the correct permissions for the API you are calling? For example, if you are attempting to create a new order, but your app does not request the ORDERS_W permission, an error is returned.
  2. Was your application configured to request the permissions it requires at the time the application was installed? If you have modified the permissions after the application was installed, 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.

Uninstalling an app

  1. Log on to your test merchant's dashboard. If you are logged into your developer dashboard you can navigate to your test merchant's dashboard using the dropdown at the top of the page (to the right of the Clover logo). Expand the dropdown and then select your test merchant under the Businesses section.
  2. On the side nav, select More Tools > Installed Apps.
  3. Find your application in the list (you may need to scroll with Next) and click it.
  4. On the right side of the application page, select ⋮ > Uninstall App.

Re-installing an app

  1. Log on to your developer dashboard.
  2. Select your application and then click Market Listing.
  3. On the market listing page, click PREVIEW IN APP MARKET.
  4. On the app market preview page, click Connect and then accept the terms of your application.

Check your app's configuration

Is your application's Default OAuth Response set to Code or Token? This setting is found in your 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 entire OAuth flow (steps 1-5).

If it is set to Token, you will receive the access token directly in step 2 of the OAuth flow.



Using a token is only allowed when testing in 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 will receive a 401.

Authenticate API requests using the Authorization Bearer header

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

Use merchant tokens correctly

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

Did this page help you?