比特浏览器API调用需要什么权限？

比特浏览器API调用主要不需要额外授权，本地调用默认即开即用。

比特浏览器API调用需要什么权限？

本地API的基础权限要求有哪些？

• 调用比特浏览器Local API的前提是用户已登录比特浏览器客户端，并且客户端处于运行状态：Local API本质上是一个运行在本地电脑上的HTTP服务，依赖于比特浏览器客户端的运行。只有客户端处于运行状态且用户已登录，API接口才能正常响应。如果关闭客户端或未登录，API将无法访问，所有请求都会失败。
• 用户需要在系统设置中开启本地API服务，才能开始调用接口：打开比特浏览器客户端，进入系统设置，找到Local API相关选项，确保“开启本地API”或“启用HTTP接口”已开启，默认端口为54345。如果该选项未开启，API接口将无法响应任何请求，这是调用API的基本前提条件。
• 获取本地接口URL后即可直接调用，无需额外的API密钥或授权验证：Local API是本地服务，所有API请求遵循POST方法和JSON参数格式，无需额外的授权验证。开发者只需获取本地接口URL（默认http://127.0.0.1:54345），即可通过HTTP请求直接调用，无需申请密钥或配置复杂的认证机制。

接口调用规范与基本权限

• 所有接口请求方式均为POST，参数通过body以JSON格式传递：接口请求方式均为post，传参方式均为body传参。不支持GET、PUT等请求方法，也不支持query string或form-data传参。请求的Content-Type需设置为application/json，否则接口将无法正确处理请求。
• 接口返回统一的JSON对象，通过success字段判断操作是否成功：接口返回json对象，success为true表示操作成功，如有返回数据附加在data对象中；success为false表示业务失败，失败信息会附加到msg字段中。开发者应根据msg内容进行针对性排查，快速定位问题根源。
• /health接口可用于检测Local API服务是否正常连接：比特浏览器3.0.9版本新增了/health接口，用来判断Local Server是否正常连接。开发者可在编写复杂脚本前先调用此接口验证环境配置是否正确，确认基础通信链路畅通。

子账号调用API时需要什么额外权限？

子账号必须传入分组ID

• 子账号创建浏览器窗口时，groupId（分组id）必须传入，否则窗口会创建到主账号下面：子账号调用API创建窗口时，必须在请求参数中指定groupId字段，否则窗口会被创建到主账号的窗口列表中，导致子账号无法管理该窗口。这是因为子账号的权限范围受分组授权的限制，未指定分组时系统默认归入主账号。
• 主账号需先在员工管理中为子账号分配分组授权：子账号调用API创建窗口的分组必须是主账号已授权给该子账号的分组。如果传入的groupId不在授权范围内，API将返回权限错误。主账号应在员工管理的“授权分组”中为子账号配置可管理的分组，确保子账号有权限操作对应的窗口环境。
• 子账号调用API时的权限范围与客户端操作一致：子账号通过API可操作的分组和窗口范围与在客户端中直接操作的范围完全相同。如果子账号在客户端中只能管理特定分组的窗口，通过API也只能操作该分组下的窗口，无法越权访问未授权的窗口数据。

子账号API调用的权限验证

• 子账号调用API时的权限验证与客户端保持一致：API接口会验证子账号的登录状态和分组授权范围，确保每个操作都在授权范围内执行。如果子账号尝试操作未授权的窗口或分组，API将返回权限错误，拒绝执行该操作。
• 主账号可在员工管理中查看和调整子账号的API调用权限：主账号通过员工管理界面可为子账号配置不同的权限级别，包括可操作的分组范围、可调用的API接口类型等。调整后子账号的API调用权限将同步更新。
• 子账号调用API时建议先确认授权分组列表：为避免权限错误，子账号在调用API前可通过主账号确认自己已被授权的分组列表，确保创建窗口时使用的groupId在授权范围内。如遇权限错误，应及时联系主账号调整分组授权。

公网环境下调用API需要什么权限配置？

开启API Token功能

• 在公网环境下调用Local API时，需要开启Local Api Token功能：比特浏览器6.0.4版本在系统设置中新增了Local Api Token功能，当需要在公网环境下调用Local API时，可开启此功能以保护信息安全。该功能默认不开启，仅在公网环境需要时才需启用，本地调用（localhost）无需配置。
• 开启Token功能后，调用API时需在HTTP请求头中添加X-API-KEY字段：开启权限控制后，调用API时需要在HTTP请求头中添加X-API-KEY字段，值为系统生成的Token值，否则API接口将无法访问。Token值可在比特浏览器系统设置中查看和复制，开发者需将其配置到自动化脚本的请求头中。
• Local Api Token功能主要用于公网环境下的信息安全保护：如果仅在本地环境（localhost/127.0.0.1）调用API，则无需开启此功能。只有当API需要从外部网络（公网）访问时，才需要启用Token验证。开发者应根据实际部署环境判断是否需要配置API Token，避免不必要的安全配置复杂度。

公网API调用的安全配置

• Token的生成和查看位于比特浏览器的系统设置中：用户进入系统设置后，在Local API相关选项中可开启权限控制，系统会自动生成对应的Token值。用户可在设置中查看、复制或重新生成Token，方便配置到自动化脚本中。
• 公网调用时需确保Token值正确且未过期：Token值是公网访问API的唯一凭证，调用时需在请求头中准确添加X-API-KEY字段。如果Token值错误或为空，API将返回权限拒绝错误。建议在脚本中配置Token时进行验证，确保Token值正确有效。
• 公网环境下的API调用路径与本地调用相同：开启Token功能后，公网调用的接口地址与本地调用相同（http://127.0.0.1:54345），只是需要在请求头中额外添加X-API-KEY字段。开发者无需修改接口路径，只需增加请求头配置即可完成公网调用的权限配置。

调用API时需要开启本地API服务吗？

开启本地API服务是调用前提

• 调用API前必须在系统设置中开启本地API服务：用户需要在比特浏览器客户端的系统设置中，确保“开启本地API”或“启用HTTP接口”已开启，默认端口为54345。如果该选项未开启，API接口将无法响应任何请求，所有调用都会失败。这是调用API的基本前提条件。
• 开启本地API服务的操作路径：打开比特浏览器客户端，点击系统设置，找到Local API相关选项，确保“开启本地API”或“启用HTTP接口”已开启。开启后客户端会启动本地HTTP服务，等待接收API请求。用户可在设置中查看当前端口号，如端口被占用可手动修改。
• Local API仅在客户端运行时提供服务，关闭客户端后API将不可用：Local API服务依赖于比特浏览器客户端的运行，关闭客户端后API将不可用。自动化脚本需确保客户端处于运行状态，建议在脚本中增加客户端状态检测逻辑（如调用/health接口验证），确保调用API前客户端已正常启动并登录。

本地API服务的验证与调试

• 通过/health接口可验证Local API服务是否正常运行：调用/health接口返回成功说明服务已就绪，是开发调试阶段验证环境配置的首选方法。建议在编写自动化脚本前先调用此接口确认服务可用，避免因服务未开启导致的调试困难。
• 如端口被占用可手动修改端口号：默认端口54345可能被其他程序占用，用户可在系统设置中修改Local API的端口号。修改后需重启客户端使新端口生效，后续所有API调用需使用新的端口号。
• API调用失败时首先检查本地服务是否已开启：如果API请求返回连接失败，第一步应检查比特浏览器系统设置中的“开启本地API”选项是否已开启，同时确认客户端是否处于运行状态。这是最基础的排查步骤，可快速排除配置问题。

API调用失败时如何排查权限问题？

基础权限排查步骤

• 检查比特浏览器客户端是否处于运行状态且已登录：如果API请求返回连接失败或服务不可用，首先确认比特浏览器客户端是否已打开并登录账号。Local API依赖于客户端的运行，客户端关闭或未登录时API无法访问。这是最基础的排查步骤，也是最常见的问题原因。
• 检查系统设置中本地API服务是否已开启：进入比特浏览器系统设置，确认“开启本地API”或“启用HTTP接口”已开启。如果该选项未开启，API请求将无法被接收。同时检查端口号是否正确（默认54345），确认端口未被其他程序占用。如端口被占用，可在设置中修改端口号并重启客户端。
• API调用失败时可通过返回的msg字段获取具体的错误信息：接口返回success为false时，msg字段会包含具体的错误描述信息，如“参数错误”“分组id必传”“窗口不存在”等。开发者应根据msg内容进行针对性排查，快速定位问题根源。

子账号与公网权限排查

• 子账号调用API时检查groupId是否已正确传入且在授权范围内：如果子账号调用API返回权限错误，首先检查创建窗口的请求中是否包含了groupId字段。如果已传入但仍有权限错误，确认该分组是否已在主账号的员工管理中授权给该子账号。未授权或分组ID错误都会导致权限错误。
• 公网环境下检查API Token是否正确配置：如果在公网环境下调用API，需要确认系统设置中已开启Local Api Token功能，并在请求头中正确添加X-API-KEY字段。Token值需与系统设置中生成的Token完全一致，否则API将返回权限拒绝错误。
• 公网调用时检查请求头是否包含正确的X-API-KEY字段：确认自动化脚本的请求头中是否包含了X-API-KEY字段，且字段值与系统设置中的Token完全一致。如果Token值错误或未包含该字段，API将返回权限错误。建议在脚本中添加Token验证逻辑，确保配置正确后再进行正式调用。