获取访问凭证

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

访问凭证是接入飞书开放平台的钥匙，将应用获得的所有数据访问和接口调用权限绑定在一起，允许应用对资源进行读写操作。建议开发者在正式开发前对飞书的访问凭证机制有充分的了解。

访问凭证介绍

飞书开放平台提供以下不同类型的访问凭证，用于对调用方身份进行鉴权。在实际开发过程中，你可以根据业务需要选择适用的访问凭证。

访问凭证类型	是否需要用户授权	说明
tenant_access_token	否	以应用身份调用 API 时需要使用的凭证，可读写的数据范围由应用的数据权限范围决定。该访问凭证适用于无需用户登录的自动化操作，例如应用机器人调用发送消息接口，向指定会话推送消息通知。该类凭证的值以`t-`为前缀，示例值：`t-24b5bf4e00b2af1234`。
user_access_token	是	以用户身份调用 API 时需要使用的凭证，可读写的数据范围由用户可读写的数据范围决定。该访问凭证适用于用户授权登录后代理用户的操作，例如，以 user_access_token 调用创建多维表格接口，创建出来的多维表格的所有者是 user_access_token 对应的用户。使用新版本接口（获取 user_access_token、刷新 user_access_token）返回的 user_access_token 示例值为 `eyJhbGciOiJFUzI1NiIs**********X6wrZHYKDxJkWwhdkrYg`其他历史版本接口返回的凭证值以`u-`为前缀，示例值为 `u-Lr1RT7S8fS03mT1234`。
app_access_token	否	应用身份的短期令牌。开放平台根据 app_access_token 识别调用方的应用身份。该类凭证的值以`a-`或者`t-`为前缀，示例值：`a-24b5cef00b1234`。

如何选择不同类型的访问凭证

API 可能支持一种或多种访问凭证，不同的访问凭证代表不同的资源访问权限，因此，使用不同的访问凭证获取到的数据信息可能不同。

确认 API 支持的访问凭证。

在调用 API 时，访问凭证需要填充到 HTTP 请求头中。在开放平台 API 文档的请求头部分，可查阅该 API 支持的访问凭证类型。

选择合适的访问凭证。

由于app_access_token的使用场景比较少（一般用于商店应用获取 tenant_access_token），飞书开放平台正在逐步统一app_access_token和tenant_access_token两个凭证。因此这里主要介绍tenant_access_token和user_access_token。

tenant_access_token

如果你的业务逻辑不需要操作用户的数据资源，仅需操作应用自身拥有的资源，例如在应用自身的文档目录空间下创建云文档，则推荐使用 tenant_access_token，无需额外申请授权。

user_access_token

如果你的业务逻辑需要操作用户的数据资源，例如需要在用户的文档目录空间下创建云文档，则推荐使用 user_access_token，无需额外申请授权。

该情况下如果使用 tenant_access_token，则需额外在资源层面为应用添加相应的授权。例如，如果使用 tenant_access_token 调用通讯录，则需在飞书开发者后台的权限管理页面配置应用的通讯录权限范围；而使用 user_access_token 则无需单独配置通讯录权限范围，遵循 user_access_token 所属用户的通讯录权限范围。

获取方式

本章节介绍企业自建应用、商店应用如何获取相应的 access_token。

访问凭证存在有效期（在调用获取访问凭证接口后，会返回有效期字段）。开发者需要在自己的服务端设置定时刷新凭证的业务逻辑，以防止过期。如果在当前凭证过期前重新获取凭证，则会拿到与原值相同的值，但每次返回的剩余有效时间会发生变化，如下图所示。

获取自建应用的 tenant_access_token

登录开发者后台，选择指定的自建应用。

在 基础信息 > 凭证与基础信息 页面，获取应用凭证 App ID 和 App Secret。

调用自建应用获取 tenant_access_token 接口，通过应用凭证 App ID 和 App Secret 获取自建应用的tenant_access_token。

获取自建应用的 app_access_token

登录开发者后台，选择指定的自建应用。

在 基础信息 > 凭证与基础信息 页面，获取应用凭证 App ID 和 App Secret。

调用自建应用获取 app_access_token 接口，通过应用凭证 App ID 和 App Secret 获取自建应用的app_access_token。

获取商店应用的 app_access_token

获取 app_ticket。

为商店应用配置事件订阅请求地址。

具体操作参见配置请求地址。完成配置后，飞书会每隔 1 小时向该地址自动推送最新的 app_ticket，应用根据接收到的 app_ticket 事件来获取并保存app_ticket，以便后续使用。

（可选）调用重新获取 app_ticket 接口，触发飞书重新推送 app_ticket。

app_ticket 推送可能存在延迟，如果没有收到推送，可以使用该方式重新推送 app_ticket。

获取应用凭证 App ID 和 App Secret。

登录开发者后台，选择指定的自建应用。

在 基础信息 > 凭证与基础信息 页面，获取应用凭证 App ID 和 App Secret。

调用商店应用获取 app_access_token 接口，通过应用凭证 App ID 和 App Secret、以及 app_ticket 获取商店应用的app_access_token。

获取商店应用的 tenant_access_token

请先获取并保存商店应用的 app_access_token，再获取商店应用的 tenant_access_token。

获取 tenant_key。

tenant_key为租户在飞书上的唯一标识，用来换取对应的 tenant_access_token，也可以用作租户在应用里面的唯一标识，可以通过如下方式获取：

企业开通应用时，开放平台推送给应用的tenant_key数据，具体可参考首次启用应用。

用户登录到小程序、H5 应用或者浏览器应用时，在用户的身份信息中获取。

调用商店应用获取 tenant_access_token 接口，通过app_access_token和tenant_key获取商店应用的tenant_access_token。

获取 user_access_token

本章节以应用的网页应用功能为例介绍如何获取 user_access_token。

获取 user_access_token 的方式同时适用于企业自建应用和商店应用。

登录开发者后台，选择指定应用。

在 开发配置 > 安全设置 页面，配置重定向 URL。

你需要将实际发起 API 请求的服务端公网地址配置为应用的重定向 URL。重定向 URL 支持配置多个，只有在重定向 URL 列表中的 URL 在请求时才会通过开放平台的安全校验。

调用获取授权登录授权码接口，获取登录预授权码 code。

调用接口时需要使用应用凭证 App ID，你可以在应用详情页的 基础信息 > 凭证与基础信息 页面，获取应用凭证 App ID。

调用获取 user_access_token接口，获取user_access_token。

同时可以获取到 Token 的有效期（expires_in 响应字段）。

（可选）调用刷新 user_access_token接口，刷新 user_access_token。

user_access_token 的有效期为两小时左右，过期后，需要刷新后再使用。

如何使用访问凭证（access_token）

使用访问凭证（access_token），需要在调用接口时将其填入到 HTTP 请求的 请求头参数 中，且该值需要增加 Bearer<空格> 前缀。

为了安全考虑，请勿在应用前端使用访问凭证。请在应用服务端发起 API 访问请求。

每个 OpenAPI 文档中，均声明了该接口需要的访问凭证类型和获取方式。

例如，cURL 请求配置示例如下：

调用 API 的详细操作参见调用 API。

访问凭证介绍#

如何选择不同类型的访问凭证#

获取方式#

获取自建应用的 tenant_access_token#

获取自建应用的 app_access_token#

获取商店应用的 app_access_token#

获取商店应用的 tenant_access_token#

获取 user_access_token#

如何使用访问凭证（access_token）#

访问凭证介绍

如何选择不同类型的访问凭证

获取方式

获取自建应用的 tenant_access_token

获取自建应用的 app_access_token

获取商店应用的 app_access_token

获取商店应用的 tenant_access_token

获取 user_access_token

如何使用访问凭证（access_token）