Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
Support scoped Cloud browser API keys
Gregor Žunič2e05ee1b5e2b
diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.pyindex 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 CloudAuthConfiglogger = 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_urlself.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_versionasync 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 configapi_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 cleanupself.current_session_id = browser_response.id+ self.current_api_version = api_versionlogger.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 configapi_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 oneif session_id == self.current_session_id:self.current_session_id = None+ self.current_api_version = Noneraise 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 oneif session_id == self.current_session_id:self.current_session_id = None+ self.current_api_version = Nonelogger.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.pyindex 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_datamock_client = AsyncMock()- mock_client.post.return_value = mock_response+ mock_client.request.return_value = mock_responsemock_client_class.return_value = mock_clientclient = 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 = Falsemock_client = AsyncMock()- mock_client.post.return_value = mock_response+ mock_client.request.return_value = mock_responsemock_client_class.return_value = mock_clientclient = CloudBrowserClient()@@ -145,7 +181,7 @@ class TestCloudBrowserClient:mock_response.json = lambda: mock_response_datamock_client = AsyncMock()- mock_client.post.return_value = mock_response+ mock_client.request.return_value = mock_responsemock_client_class.return_value = mock_clientclient = 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_datamock_client = AsyncMock()- mock_client.patch.return_value = mock_response+ mock_client.request.return_value = mock_responsemock_client_class.return_value = mock_clientclient = 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 Noneasync 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 = Falsemock_client = AsyncMock()- mock_client.patch.return_value = mock_response+ mock_client.request.return_value = mock_responsemock_client_class.return_value = mock_clientclient = CloudBrowserClient()