David Marginian avatar image
David Marginian Posted · · edited ·

Resolving 401 (Unauthorized) responses when making API calls

Receiving a 401 (Unauthorized) response when making an API call is a common problem for new Clover developers. This article discusses the possible causes of this error and how to resolve them.


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

Check your request

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 (e.g. 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.

App 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 via the OAuth flow. This is necessary to protect our merchants as they accept the permissions and terms of your application when they install it.

How to uninstall 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 via 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 sidenav, 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.

How to re-install 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.

App 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. Please note that using a Token is only allowed when testing in sandbox.

OAuth Flow

If your application's Default OAuth Response is set to Code, are you certain 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.

10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Welcome to the
Clover Developer Community



david.marginian contributed to this article Dex_Cook contributed to this article

Related Articles