401 Unauthorized

United States
Latin America

401 Unauthorized indicates the request lacks valid authentication credentials for the target resource. Some examples when this error displays include: incorrect link (URL), incorrect login attempts, outdated browser cache and cookies, server configuration errors, and IP restrictions.

Use the following guidelines to troubleshoot 401 errors.

Use the right environment

Clover sandbox and production are separate environments. Ensure 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) and returns a 401 Unauthorized in either case.

Check the following:

  • Does your application request the correct permissions for the API you call?
    Example: An error is returned if you are attempting to create a new order, but your app does not request the ORDERS_W permission.
  • Did you edit the required permissions for your app after merchants installed it?
    Example: You have modified the permissions after merchants installed your application. In this case, your merchants must uninstall and reinstall the application and generate a new access token using the OAuth flow. This is necessary to protect our merchants as they accept 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 default OAuth response

Verify if the 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 settings. You can use a token only when testing in the sandbox environment.

  • 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.

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, authentication requests using the access_token query parameter result in a 401 - Unauthorized response.

Use merchant tokens correctly

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