Applitools Eyes API Key Authentication Error Fix

If an Applitools Eyes test returns 401 Unauthorized, first verify that the test is using the API key for the intended Applitools account. Then confirm the key reaches the process that launches the test. If the account uses a private cloud or on-premise Eyes deployment, check that its deployment-specific server URL is configured. Applitools identifies a wrong key and a missing private-deployment server URL as usual causes; they are not an exhaustive diagnosis for every SDK or tool. Applitools Dashboard documentation · Applitools 401 support article.

1. Confirm the key belongs to the intended account

Sign in to the Applitools Dashboard for the team where the visual test should appear.
Open the account menu or avatar and select My API key.
Copy that account’s execution key and update the secret used by the test runner.

A key copied from another account or team can be syntactically valid but authenticate against the wrong account context. Do not paste a live key into a support post, source control, or build log.

2. Make the key available to the process that runs the test

Applitools’ documented environment variable for test execution is APPLITOOLS_API_KEY. Set it in the environment of the actual test process. A variable exported in one terminal will not automatically reach a different IDE, CI job, container, or remote runner.

Shell example

export APPLITOOLS_API_KEY='YOUR_APPLITOOLS_EXECUTION_KEY'
# Run your existing test command in this same shell
./gradlew test

Replace the test command with the command used by your project. Store the key in a protected CI secret or secret manager and map it into the job environment. Avoid echoing it or printing the full process environment.

Java test setup

Set the variable before launching the test process. For an IDE, add it to the run configuration for the test, rather than assuming the IDE inherited it from a terminal.

APPLITOOLS_API_KEY=YOUR_APPLITOOLS_EXECUTION_KEY
# Then launch the test from the IDE or build tool

This is an environment configuration example, not a standalone Eyes test: retain your project’s existing SDK setup and test code.

Python with Appium

The documented Appium Python setup supports either an environment variable or assigning a key to the Eyes object. Prefer environment injection for shared or committed code; use a protected runtime secret if configuration must be explicit.

import os
from applitools.selenium import Eyes

eyes = Eyes()
eyes.api_key = os.environ["APPLITOOLS_API_KEY"]
# Continue with your existing Appium/Eyes test setup

Do not put a real key literal in a committed test file. The snippet illustrates key configuration and does not replace the rest of the Appium test lifecycle.

3. Check the server URL for private Eyes deployments

If your organization uses a private cloud or on-premise Eyes deployment, obtain its server URL from the deployment or account administrator and configure the endpoint required by your SDK. A private deployment may reject a correct key if the test is sent to the wrong server.

The Figma plugin documentation lists https://eyes.applitools.com as the public default and advises checking the URL for private Eyes clouds. Do not copy that public URL into a private deployment without verifying the endpoint. Public-cloud users should follow their account’s documented public configuration; a server URL change is not always required. Eyes Figma Plugin documentation.

4. Use the key intended for the operation

For ordinary visual test execution, configure APPLITOOLS_API_KEY. Applitools documents separate APPLITOOLS_READ_KEY and APPLITOOLS_WRITE_KEY variables for specified Applitools MCP inspection, resolution, and review operations. If the 401 comes from an MCP tool rather than a visual test run, check the permission key required for that particular operation. These key roles are not interchangeable. See Applitools MCP Server documentation.

5. Retest one configuration change at a time

Record the sanitized error, SDK or tool name and version, whether the deployment is public or private, and where the process gets its secret.
Change one item: account key, environment propagation, or private server URL.
Rerun the same test and compare the result.
If the 401 remains, share the sanitized details with your team or Applitools support. Never include the API key itself.

There is no universal SDK configuration precedence established by the sources cited here. If both an environment variable and an explicit SDK setting exist, consult the documentation for the specific SDK and version in use.

Common errors and fixes

Symptom or setup	Likely cause	What to check
`401 Unauthorized` after a key change	The runner still receives an old, empty, or different key.	Update the secret in the environment that actually launches the test, then restart the IDE, container, or runner as needed.
The test appears under an unexpected account	The key belongs to a different account or team.	Copy the execution key from the intended account’s Dashboard.
Local run works but CI fails	The CI job does not have the local shell’s environment.	Map the protected CI secret to `APPLITOOLS_API_KEY` in the job or runner context.
Public setup works but private deployment fails	The test may be targeting the wrong Eyes server.	Set the deployment-specific URL supplied by the private-cloud or on-premise administrator.
An MCP inspection or review action returns an auth error	The operation may need a read or write key rather than the test execution key.	Check the documented key requirement for that MCP operation.
Error persists after these checks	Other SDK, account, or endpoint details may be involved.	Collect the sanitized exception, tool and version, hosting type, and secret-injection path. Do not expose the credential.

Reliability, security, and cost notes

Reliability: Keep the key in the runner’s secret store and validate that the job maps it into the process environment. A successful local run does not establish that CI or another container has the same configuration.
Security: Do not commit keys, print them in logs, include them in screenshots, or send them in support requests. Rotate a key if it has been exposed, then update every runner that uses it.
Cost: Authentication troubleshooting does not require buying hardware. Any Eyes account or plan costs are account-specific; consult Applitools for current terms rather than inferring them from a 401.

Or skip the browser setup

If the task is to capture a website screenshot rather than run a visual test in Eyes, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Where do I find my Applitools Eyes API key?

Open the intended account in the Applitools Dashboard, open the account menu, and choose “My API key.”

Should I change the server URL for every 401?

No. Check the server URL when the account uses a private-cloud or on-premise deployment. Public users should follow their account’s documented public configuration.

Can I send my API key to support to speed up diagnosis?

No. Share the sanitized error and configuration context, never the secret value.

Does a ScreenshotNeo screenshot replace an Applitools visual test?

No. ScreenshotNeo captures web pages as images or PDFs. Applitools Eyes is the product involved in this Eyes test authentication error.