申请 API 权限

通过本文你可以了解什么是应用的 API 权限，以及如何为应用申请 API 权限。

什么是 API 权限

在开发应用过程中，你可能需要调用服务端 API或监听已订阅的事件，该类操作可能涉及访问企业、用户的隐私信息，也可能需要操作企业、用户的应用数据。出于安全考虑，你需要为应用申请相应的权限，并且由企业管理员审核通过后，应用才可以进行后续的 API 调用或事件监听。简单来说，应用的 API 权限（Scope）决定了应用能使用哪些飞书服务端的开放能力。

API 权限是以应用为维度授予的，每个应用的 API 权限都是独立存在的，若多个应用需要调用同一个 API ，那么每个应用都要添加对应的 API 权限。

开放平台支持的所有权限，可参考API 权限列表。

权限类型

为了提升 API 调用的安全性，飞书开放平台设计了访问凭证（access_token）机制，调用 API 获取应用资源时，需要通过 access_token 对调用者身份进行鉴权，即告知飞书当前是谁、以什么身份获取什么租户的数据。关于如何选择和获取不同类型 access token，参考获取访问凭证。

调用 API 时，以用户身份（user_access_token）调用和以应用身份（tenant_access_token）调用的权限敏感等级不同，涉及的风险程度不同，因此对应的审核要求也不同，开发者申请权限时需要区分用户身份、应用身份。

为了更好地支持权限最小化原则，根据权限所归属的不同身份主体，开放平台将 API 权限划分为以下两种类型：

权限类型	描述	场景示例
应用身份权限 tenant_access_token	以 tenant_access_token 调用 API 或者订阅事件时，需要申请应用身份权限。	假设有一个应用名为 “My bot”，该应用：调用创建多维表格接口时，如果以 tenant_access_token 调用，则多维表格的所有者是 “My bot”。订阅云文档变更事件时，如果以 tenant_access_token 订阅，则仅能订阅 “My bot” 作为拥有者或者管理员的文档变更，无法感知其他文档变更。
用户身份权限 user_access_token	以 user_access_token 调用 API 或者订阅事件时，需要申请用户身份权限。	假设有一个应用名为 “My bot”，该应用：调用创建多维表格接口时，如果以 user_access_token 调用，且该 token 代表用户 “李健”，则多维表格的所有者是 “李健”。订阅云文档变更事件时，如果以 user_access_token 订阅，该 token 代表的用户是 “李健”，则仅能订阅 “李健” 作为拥有者或者管理员的文档变更，无法感知其他文档变更。

权限等级

在商店应用、自建应用两类不同的应用中，权限存在不同的等级划分。你可以通过下表了解不同应用类型中的权限等级划分情况。关于权限等级的划分原则及平台推荐的默认审核规则，参考自建应用的权限介绍和审核规则推荐。

自建应用

是否需要审核	权限说明	权限审核规则
免审权限	企业管理员可以根据本企业实际数据管控诉求，配置免审权限来减轻审核负担。具体配置方法，可参见管理员如何设置自建应用审核规则。	无需审核，申请后立即生效。
需审核权限	对于涉及敏感数据的权限，请纳入需审核权限列表。	申请后，需要创建版本并提交审核，由应用管理员审核通过后才可生效。

商店应用

权限等级	权限说明	权限审核规则
普通权限	访问的数据敏感程度不高。	对于商店应用，所有的权限操作都需要经过以下审核流程：应用上架流程审核：由飞书开放平台审核。租户安装应用流程审核：由租户管理员在版本更新时审核。
高级权限	访问的数据敏感程度较高。如无必要原因，申请高级权限时不会通过审核。	对于商店应用，所有的权限操作都需要经过以下审核流程：应用上架流程审核：由飞书开放平台审核。租户安装应用流程审核：由租户管理员在版本更新时审核。

权限申请原则

权限的申请应该遵循最小可用原则，权限范围过大可能会威胁企业数据安全管控。在无充分理由的情况下，请注意避免直接申请大量接口权限。因此，在飞书开放体系中，权限的管控有严格的审核流程。

企业自建应用：应用开发者申请的权限需要通过 租户管理员 的审核。租户管理员可以按需配置审核规则和审核方式，参考自建应用发版审核指南。

ISV 开发的商店应用：如需申请权限，需要通过飞书开放平台发布应用时和租户安装应用时的两道审核流程。

如下图所示，商店应用在初次安装和版本更新时会接收到授权提醒。租户管理员可以按需设置管理规则，参考审核应用的获取与使用申请。

确定所需申请的权限

当你在实际开发应用时，可根据 API 或事件的开发文档获取相应的权限信息。以获取单个用户信息接口为例，在相应的接口文档中，你可以获取接口的权限要求、字段权限要求等信息。

其中：

权限要求：代表整个接口的权限要求，该类权限之间是或关系，即应用申请任一权限即可调用该接口。

字段权限要求：展示了获取响应体字段数据所需的权限要求。

例如下图，自建应用想要获取响应体中的user_id字段值，则必须开通 获取用户 user ID 权限。

为企业自建应用申请 API 权限

步骤一：申请权限

登录开发者后台，进入指定自建应用。

在左侧导航栏进入 开发配置 > 权限管理 页，点击 开通权限 按钮。

在弹出页面中选择所需权限，点击 确认开通权限，系统自动跳转到已申请的权限列表页面。

注意在不同的页签下进行不同类型权限的申请。

如需使用应用身份凭证（tenant_access_token）进行调用相关 API，还需为应用配置可访问的数据范围，参考配置应用数据权限。

以用户身份（ user_access_token）调用时，可读写的数据范围与用户本人可读写的数据范围一致，无需单独配置数据权限。

选择完成后，在 权限配置 区域右上角点击 批量开通。

步骤二：免审核 API 权限进行测试联调

在应用的测试联调阶段，你可以通过以下路径，无需审核通过即可生效 需审核权限，进行 API 调试。

方式一：使用 user_access_token 调试 API

批量申请 API 权限时，如果权限支持通过应用开发者的 user_access_token 免审调用 API ，则在申请权限后，无需发布应用即可使用 user_access_token 调试 API。

以调用列出自定义角色接口为例，在调用前需要在应用的 API 权限 功能页中，申请 查看、评论、编辑和管理多维表格 或者 查看、评论和导出多维表格 权限。

申请后，无需发布应用并等待审核通过，直接使用应用开发者的用户访问凭证（user_access_token）即可调试 API。

方式二：使用测试企业调试 API

在 API 权限中，存在不支持 user_access_token 鉴权的 API，且支持 user_access_token 鉴权的 API 中也存在少量的敏感权限基于 user_access_token 无法免审调试 API。该类权限在申请时可以通过提示查看（如下图所示）。

此时，你可以为应用配置测试企业和人员，并切换为测试版本（具体操作参见测试企业与人员）。切换后，前往 开发配置 > 权限管理 页面，在 API 权限 页签申请指定权限，申请的权限均为 免审权限，点击确认后立即生效。

如果你申请了 通讯录 或者 飞书人事（企业版） API 权限，且需要通过应用身份（tenant_access_token）调用相关 API，则需要为应用配置相应的数据权限。详情参见配置应用数据权限。

步骤三：正式发布应用

确保测试联调阶段申请的权限符合预期后，你可以提交应用的正式版本发布申请。

在 应用发布 > 版本管理与发布 页面，点击 创建版本。

使用测试企业调试 API 的场景中，开通的权限不会生效于应用的正式版本。因此在完成测试联调后，需要切换至正式版本的应用，为正式版应用再次开通相同的 API 权限。你可以使用批量导入导出功能，进行应用间的权限数据迁移。

在 版本详情 页面，配置以下字段，并点击保存。

应用版本号：自定义应用版本号，格式示例：1.0.0。

更新说明：自定义当前版本的更新详情。

应用能力、权限变更：查看并确认添加的能力、权限是否符合预期。

可用范围：应用的可用范围。可点击编辑，调整可用范围。关于可用范围的说明可参见配置应用可用范围。

申请理由：用于帮助审核人员了解更多应用版本信息。

在弹出的对话框中，点击 申请线上发布。

等待企业管理员审核应用。

当应用通过审核后，所有的 API 权限才会正式生效。