Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Support scoped Cloud browser API keys

Gregor Žunič2e05ee1b5e2b
diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.py
index ddf264298..9b2c240a1 100644
--- a/browser_use/browser/cloud/cloud.py
+++ b/browser_use/browser/cloud/cloud.py
@@ -15,6 +15,8 @@ from browser_use.sync.auth import CloudAuthConfig
logger = logging.getLogger(__name__)
+_BROWSER_API_VERSIONS = ('v2', 'v3', 'v4')
+
class CloudBrowserClient:
"""Client for browser-use cloud browser service."""
@@ -23,11 +25,50 @@ class CloudBrowserClient:
self.api_base_url = api_base_url
self.client = httpx.AsyncClient(timeout=30.0)
self.current_session_id: str | None = None
+ self.current_api_version: str | None = None
+
+ @staticmethod
+ def _missing_version_scope(response: httpx.Response) -> bool:
+ if response.status_code != 403:
+ return False
+ try:
+ detail = response.json().get('detail', '')
+ except Exception:
+ return False
+ return isinstance(detail, str) and detail.startswith('API key is missing required scope:')
+
+ async def _request_browser_api(
+ self,
+ method: str,
+ path: str,
+ *,
+ headers: dict[str, str],
+ json: dict,
+ ) -> tuple[httpx.Response, str]:
+ """Use the session's API version, or find the first version granted to this key.
+
+ The Cloud backend mounts the same standalone-browser router under V2, V3,
+ and V4, while scoped keys grant access per version. Preserve V2 behavior
+ for existing keys and only fall through on the backend's explicit
+ missing-version-scope response.
+ """
+ versions = (self.current_api_version,) if self.current_api_version else _BROWSER_API_VERSIONS
+ last_response = None
+ last_version = versions[-1]
+ for version in versions:
+ url = f'{self.api_base_url}/api/{version}/browsers{path}'
+ response = await self.client.request(method, url, headers=headers, json=json)
+ last_response = response
+ last_version = version
+ if not self._missing_version_scope(response):
+ return response, version
+ assert last_response is not None
+ return last_response, last_version
async def create_browser(
self, request: CreateBrowserRequest, extra_headers: dict[str, str] | None = None
) -> CloudBrowserResponse:
- """Create a new cloud browser instance. For full docs refer to https://docs.cloud.browser-use.com/api-reference/v-2-api-current/browsers/create-browser-session-browsers-post
+ """Create a new cloud browser instance.
Args:
request: CreateBrowserRequest object containing browser creation parameters
@@ -35,8 +76,6 @@ class CloudBrowserClient:
Returns:
CloudBrowserResponse: Contains CDP URL and other browser info
"""
- url = f'{self.api_base_url}/api/v3/browsers'
-
# Try to get API key from environment variable first, then auth config
api_token = os.getenv('BROWSER_USE_API_KEY')
@@ -62,7 +101,7 @@ class CloudBrowserClient:
try:
logger.info('🌤️ Creating cloud browser instance...')
- response = await self.client.post(url, headers=headers, json=request_body)
+ response, api_version = await self._request_browser_api('POST', '', headers=headers, json=request_body)
if response.status_code == 401:
raise CloudBrowserAuthError(
@@ -86,6 +125,7 @@ class CloudBrowserClient:
# Store session ID for cleanup
self.current_session_id = browser_response.id
+ self.current_api_version = api_version
logger.info(f'🌤️ Cloud browser created successfully: {browser_response.id}')
logger.debug(f'🌤️ CDP URL: {browser_response.cdpUrl}')
@@ -124,8 +164,6 @@ class CloudBrowserClient:
if not session_id:
raise CloudBrowserError('No session ID provided and no current session available')
- url = f'{self.api_base_url}/api/v3/browsers/{session_id}'
-
# Try to get API key from environment variable first, then auth config
api_token = os.getenv('BROWSER_USE_API_KEY')
@@ -150,7 +188,7 @@ class CloudBrowserClient:
try:
logger.info(f'🌤️ Stopping cloud browser session: {session_id}')
- response = await self.client.patch(url, headers=headers, json=request_body)
+ response, _ = await self._request_browser_api('PATCH', f'/{session_id}', headers=headers, json=request_body)
if response.status_code == 401:
raise CloudBrowserAuthError(
@@ -162,6 +200,7 @@ class CloudBrowserClient:
# Clear current session if it was this one
if session_id == self.current_session_id:
self.current_session_id = None
+ self.current_api_version = None
raise CloudBrowserError(f'Cloud browser session {session_id} not found')
elif not response.is_success:
error_msg = f'Failed to stop cloud browser: HTTP {response.status_code}'
@@ -179,6 +218,7 @@ class CloudBrowserClient:
# Clear current session if it was this one
if session_id == self.current_session_id:
self.current_session_id = None
+ self.current_api_version = None
logger.info(f'🌤️ Cloud browser session stopped: {browser_response.id}')
logger.debug(f'🌤️ Status: {browser_response.status}')
diff --git a/tests/ci/browser/test_cloud_browser.py b/tests/ci/browser/test_cloud_browser.py
index 7ff0dcaef..0edcb65f1 100644
--- a/tests/ci/browser/test_cloud_browser.py
+++ b/tests/ci/browser/test_cloud_browser.py
@@ -66,7 +66,7 @@ class TestCloudBrowserClient:
mock_response.json = lambda: mock_response_data
mock_client = AsyncMock()
- mock_client.post.return_value = mock_response
+ mock_client.request.return_value = mock_response
mock_client_class.return_value = mock_client
client = CloudBrowserClient()
@@ -79,11 +79,47 @@ class TestCloudBrowserClient:
assert result.cdpUrl == 'wss://test.proxy.daytona.works'
# Verify auth headers were included
- mock_client.post.assert_called_once()
- call_args = mock_client.post.call_args
- assert call_args.args[0] == 'https://api.browser-use.com/api/v3/browsers'
+ mock_client.request.assert_called_once()
+ call_args = mock_client.request.call_args
+ assert call_args.args[:2] == ('POST', 'https://api.browser-use.com/api/v2/browsers')
assert 'X-Browser-Use-API-Key' in call_args.kwargs['headers']
assert call_args.kwargs['headers']['X-Browser-Use-API-Key'] == 'test-token'
+ assert client.current_api_version == 'v2'
+
+ async def test_create_browser_falls_through_version_scopes(self, mock_auth_config, monkeypatch):
+ monkeypatch.delenv('BROWSER_USE_API_KEY', raising=False)
+ missing_scope = AsyncMock()
+ missing_scope.status_code = 403
+ missing_scope.is_success = False
+ missing_scope.json = lambda: {'detail': 'API key is missing required scope: v2:browsers:create'}
+ created = AsyncMock()
+ created.status_code = 201
+ created.is_success = True
+ created.json = lambda: {
+ 'id': 'test-browser-id',
+ 'status': 'active',
+ 'liveUrl': 'https://live.browser-use.com?wss=test',
+ 'cdpUrl': 'wss://test.proxy.daytona.works',
+ 'timeoutAt': '2025-09-17T04:35:36.049892',
+ 'startedAt': '2025-09-17T03:35:36.049974',
+ 'finishedAt': None,
+ }
+
+ with patch('httpx.AsyncClient') as mock_client_class:
+ mock_client = AsyncMock()
+ mock_client.request.side_effect = [missing_scope, created]
+ mock_client_class.return_value = mock_client
+ client = CloudBrowserClient()
+ client.client = mock_client
+
+ result = await client.create_browser(CreateBrowserRequest())
+
+ assert result.id == 'test-browser-id'
+ assert [call.args[:2] for call in mock_client.request.call_args_list] == [
+ ('POST', 'https://api.browser-use.com/api/v2/browsers'),
+ ('POST', 'https://api.browser-use.com/api/v3/browsers'),
+ ]
+ assert client.current_api_version == 'v3'
async def test_create_browser_auth_error(self, temp_config_dir, monkeypatch):
"""Test cloud browser creation with auth error."""
@@ -110,7 +146,7 @@ class TestCloudBrowserClient:
mock_response.is_success = False
mock_client = AsyncMock()
- mock_client.post.return_value = mock_response
+ mock_client.request.return_value = mock_response
mock_client_class.return_value = mock_client
client = CloudBrowserClient()
@@ -145,7 +181,7 @@ class TestCloudBrowserClient:
mock_response.json = lambda: mock_response_data
mock_client = AsyncMock()
- mock_client.post.return_value = mock_response
+ mock_client.request.return_value = mock_response
mock_client_class.return_value = mock_client
client = CloudBrowserClient()
@@ -158,8 +194,9 @@ class TestCloudBrowserClient:
assert result.cdpUrl == 'wss://test.proxy.daytona.works'
# Verify environment variable was used
- mock_client.post.assert_called_once()
- call_args = mock_client.post.call_args
+ mock_client.request.assert_called_once()
+ call_args = mock_client.request.call_args
+ assert call_args.args[0] == 'POST'
assert 'X-Browser-Use-API-Key' in call_args.kwargs['headers']
assert call_args.kwargs['headers']['X-Browser-Use-API-Key'] == 'env-test-token'
@@ -187,7 +224,7 @@ class TestCloudBrowserClient:
mock_response.json = lambda: mock_response_data
mock_client = AsyncMock()
- mock_client.patch.return_value = mock_response
+ mock_client.request.return_value = mock_response
mock_client_class.return_value = mock_client
client = CloudBrowserClient()
@@ -203,11 +240,15 @@ class TestCloudBrowserClient:
assert result.finishedAt is not None
# Verify correct API call
- mock_client.patch.assert_called_once()
- call_args = mock_client.patch.call_args
- assert call_args.args[0] == 'https://api.browser-use.com/api/v3/browsers/test-browser-id'
+ mock_client.request.assert_called_once()
+ call_args = mock_client.request.call_args
+ assert call_args.args[:2] == (
+ 'PATCH',
+ 'https://api.browser-use.com/api/v2/browsers/test-browser-id',
+ )
assert call_args.kwargs['json'] == {'action': 'stop'}
assert 'X-Browser-Use-API-Key' in call_args.kwargs['headers']
+ assert client.current_api_version is None
async def test_stop_browser_session_not_found(self, mock_auth_config, monkeypatch):
"""Test stopping a browser session that doesn't exist."""
@@ -221,7 +262,7 @@ class TestCloudBrowserClient:
mock_response.is_success = False
mock_client = AsyncMock()
- mock_client.patch.return_value = mock_response
+ mock_client.request.return_value = mock_response
mock_client_class.return_value = mock_client
client = CloudBrowserClient()