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.

Guidelines to troubleshoot 401 errors are:

1. Use the right Clover environment

Clover sandbox and production are separate environments. You can access and use different environments based on specific regions:

• North America—United States and Canada: Create a single developer account and access both the sandbox and production environments on the Global Developer Dashboard. See Get started with the global developer platform.
• Europe and Latin America: Create separate developer accounts on the sandbox environment and the region-based production environments.

Make sure you are executing your request in the correct Clover environment.

2. Use the correct URL (link) for the environment

3. Make sure your request has no errors

1. Check for typing errors in requests, as these often cause a 401 error.
2. Make sure that the access token is passed correctly. The merchant ID required for our REST API is a 13-alphanumeric identifier that displays the merchant name in the Merchant column. Example: TC4DGCJW1K4EW. See Locate the test merchant ID.
3. Check if you are using the v1 app code URL for the /v2/token endpoint. Be sure to use the updated v2 auth code URL: https\://{clover_server}.clover.com/oauth/v2/authorize?client_id={app_id}&redirect_uri=http\://{app_site_URL}

4. 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 permissions) and returns a 401 Unauthorized in either case.

Check the following:

• Does your application request the correct permissions for the API you call?
  Example: If you try to create a new order but your app does not request the ORDERS_W permission, an error will appear.
• Did you edit the required permissions for your app after merchants installed it?
  Example: You have modified the permissions after merchants installed your app. 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 app 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 Clover App Market page appears.
4. From the top-right menu, click My Apps.
5. Find your app in the list; if needed, click Next to find it.
6. For the app, in the Actions column, click the ⋮ icon and click Uninstall app.

Reinstall an app

1. Log in to the Developer Dashboard.
2. From the left navigation menu > Dashboard > Your Apps, select your app.
3. Click Market Listing. The App Name - Market Listing page appears.
4. Click Preview in App Market. The app page appears.
5. Click Connect, and complete the steps in the reinstall workflow.

5. Check your app's default OAuth response

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

6. Use the correct OAuth flow

When a merchant selects and installs your app from the Merchant Dashboard left navigation menu or the Clover App Market (in production environments), the OAuth flow begins. Clover uses OAuth to secure the communication between your app and the merchant and then gives your app the necessary access to merchant data.

Use the correct OAuth flow based on the regions in which you create apps.

• If you create apps in the North America—United States and Canada, see Authenticate with OAuth—Canada and US to create or migrate to expiring access (authentication) tokens.
• If you create apps in Europe or Latin America, see Use OAuth 2.0—Europe and Latin America to acquire API tokens. Note the following for the OAuth 2.0 flow based on your app's Default OAuth Response:
  • If set to Code, complete all steps of the OAuth 2.0 flow. When your test merchant is authorized through OAuth 2.0, you receive an authorization code. This code is required for you to request an API token for your app permissions. The code in Step 2: Receive an authorization code is not an access token. If you try to pass this code as an access token, you receive a 401 - Unauthorized error.
  • If set to Token, you receive the access token directly in Step 2: Receive an authorization code. You can use a token only when testing in the sandbox environment. See Generate an API token.

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

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