BrowserStack Screenshot API Returns 401: How to Fix Authentication
Fix BrowserStack Screenshots API 401 errors by checking Basic Auth, account credentials, key rotation, and plan eligibility.
If BrowserStack’s Screenshots API returns 401 Unauthorized, first check that your request uses HTTP Basic Auth with your BrowserStack username as the username and your current access key as the password. Then verify that both values are present and belong to the right account, check whether the key was rotated, and confirm that your plan includes Screenshots API access.
The documented endpoint is https://www.browserstack.com/screenshots. BrowserStack’s Screenshots API documentation says requests use the account username and access key as HTTP Basic Auth credentials, and that an unauthorized request receives 401. [BrowserStack Screenshots API documentation]
1. Check the authentication format
Use the BrowserStack account username as the Basic Auth username and the access key as the password. Do not put the key in the username field, and do not substitute your account password for the access key.
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://www.browserstack.com/screenshots"For a script or API client, configure the equivalent HTTP Basic Auth pair. Avoid placing real credentials directly in source code, shell history, or logs.
2. Verify the username and access key
- Open BrowserStack Account Settings and locate the account username and access key.
- Compare the values with the secrets used by the failing request. Check that neither is empty and that both come from the same account.
- Inspect environment-variable names and CI secret mappings for typos. Watch for accidental leading or trailing whitespace when copying values.
- Retry with the exact endpoint and Basic Auth format shown above.
BrowserStack documents Account Settings as the place to find the username and access key. [Manage access keys]
3. Check whether the access key was rotated
Rotating the access key invalidates the previous key. If the key changed, update every place that stores it, including local environment files, CI secret stores, scheduled jobs, and deployment configuration. Restart or redeploy processes that keep the old value in memory, then retry.
BrowserStack explicitly notes that rotating an access key invalidates the existing one. [Manage access keys]
4. Confirm Screenshots API plan eligibility
BrowserStack says the Screenshots API is available on Automate plans that include browsers. A Live-only subscription is directed to use Screenshots through the webpage. Check your subscription if the credentials and request format are correct. The documentation does not state that every plan-access issue returns 401, so treat plan eligibility as an access check rather than a guaranteed explanation for this status.
See BrowserStack’s Screenshots API documentation for the product’s access requirements.
5. Keep the endpoint specific to this API
BrowserStack has multiple APIs, and their hosts and paths can differ. Use the documented Screenshots API endpoint for this operation; do not copy an endpoint from another BrowserStack product just because it also uses Basic Auth. BrowserStack’s Automate API authentication page, for example, describes authentication for a different API. [Automate API authentication]
Troubleshooting checklist
| What to check | Likely issue | Fix |
|---|---|---|
| Basic Auth fields | The access key is in the username field, or the account password is used instead of the key. | Send username as the Basic Auth username and access key as the password. |
| Credential values | An environment variable is unset, misspelled, copied with whitespace, or belongs to another account. | Read the values from Account Settings and verify the script or CI secret mapping. |
| Recent key change | The integration still holds a key invalidated by rotation. | Replace the old key in every secret store and restart processes using it. |
| Subscription | The account may not have an Automate plan with browsers. | Confirm plan eligibility with BrowserStack; the docs do not promise that this condition always produces 401. |
| Host and path | The request targets an endpoint copied from another BrowserStack API. | Use https://www.browserstack.com/screenshots for the Screenshots API example. |
Reliability and credential handling
- Store the username and access key in your CI or deployment secret manager rather than committing them to a repository.
- When rotating a key, update all consumers as one coordinated change so scheduled jobs do not keep sending the invalidated value.
- Do not print the full Authorization header or credentials in diagnostic logs. Log the endpoint and response status while redacting secrets.
- Test the same credential source your production job uses. A successful local request does not confirm that the CI environment has the same secret values.
Or skip the browser setup
If your task is to capture a webpage rather than use BrowserStack specifically, ScreenshotNeo is a screenshot API and MCP server for developers. Its one-call API returns a screenshot or PDF, and its parameter names are compatible with those used by other screenshot APIs.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpSee the ScreenshotNeo API documentation for request options and configuration. Cookie banners are accepted and removed before the shot, along with 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Does BrowserStack use an access key or my account password?
The Screenshots API example uses your account username and BrowserStack access key as HTTP Basic Auth credentials.
Will changing my access key fix every 401?
Only if the stored key was invalid or had been rotated. Also verify the username, Basic Auth placement, endpoint, and plan eligibility.
Does a Live-only plan include the Screenshots API?
BrowserStack’s documentation says the API is available on Automate plans that include browsers; Live-only users are directed to Screenshots on the webpage.
Where can I confirm the required credentials?
BrowserStack directs users to Account Settings for the username and access key. See its access-key guide.
