服务端 API/API 调用指南/调用流程/获取访问凭证
# 获取访问凭证
为了提升 API 调用的安全性，Lark开放平台设计了访问凭证（access_token）机制，调用 API 获取应用资源时，需要通过 access_token 对调用者身份进行鉴权，即告知Lark当前是谁、以什么身份获取什么租户的数据。
访问凭证是接入Lark开放平台的钥匙，将应用获得的所有数据访问和接口调用权限绑定在一起，允许应用对资源进行读写操作。建议开发者在正式开发前对Lark的访问凭证机制有充分的了解。
## 访问凭证介绍
Lark开放平台提供以下不同类型的访问凭证，用于对调用方身份进行鉴权。在实际开发过程中，你可以根据业务需要选择适用的访问凭证。
访问凭证类型 | 是否需要用户授权 | 说明
---|---|---
tenant_access_token | 否 | 以应用身份调用 API 时需要使用的凭证，可读写的数据范围由应用的[数据权限范围](https://open.larksuite.com/document/home/introduction-to-scope-and-authorization/configure-app-data-permissions)决定。
该类凭证的值以`t-`为前缀，示例值：`t-24b5bf4e00b2af1234`。
user_access_token | 是 | 以用户身份调用 API 时需要使用的凭证，可读写的数据范围由用户可读写的数据范围决定。
该类凭证的值以`u-`为前缀，示例值：`u-Lr1RT7S8fS03mT1234`。
app_access_token | 否 | 应用身份的短期令牌。开放平台根据 app_access_token 识别调用方的应用身份。
该类凭证的值以`a-`或者`t-`为前缀，示例值：`a-24b5cef00b1234`。
## 如何选择不同类型的访问凭证
API 可能支持一种或多种访问凭证，不同的访问凭证代表不同的资源访问权限，因此，使用不同的访问凭证获取到的数据信息可能不同。
1. 确认 API 支持的访问凭证。
在调用 API 时，访问凭证需要填充到 HTTP 请求头中。在开放平台 API 文档的请求头部分，可查阅该 API 支持的访问凭证类型。
2. 选择合适的访问凭证。warning
由于`app_access_token`的使用场景比较少（一般用于[获取 user_access_token](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/authen-v1/oidc-access_token/create)、[刷新 user_access_token](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/authen-v1/oidc-refresh_access_token/create)），Lark开放平台正在逐步统一`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 调用通讯录，则需在Lark开发者后台的权限管理页面配置应用的通讯录权限范围；而使用 user_access_token 则无需单独配置通讯录权限范围，遵循 user_access_token 所属用户的通讯录权限范围。
## 获取方式
本章节介绍企业自建应用、商店应用如何获取相应的 access_token。
访问凭证存在有效期（在调用获取访问凭证接口后，会返回有效期字段）。开发者需要在自己的服务端设置定时刷新凭证的业务逻辑，以防止过期。如果在当前凭证过期前重新获取凭证，则会拿到与原值相同的值，但每次返回的剩余有效时间会发生变化，如下图所示。
### 获取自建应用的 tenant_access_token
1. 登录[开发者后台](https://open.larksuite.com/app/)，选择指定的自建应用。
2. 在 **基础信息** > **凭证与基础信息** 页面，获取应用凭证 **App ID** 和 **App Secret**。
3. 调用[自建应用获取 tenant_access_token](https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/tenant_access_token_internal) 接口，通过应用凭证 App ID 和 App Secret 获取自建应用的`tenant_access_token`。
### 获取自建应用的 app_access_token
1. 登录[开发者后台](https://open.larksuite.com/app/)，选择指定的自建应用。
2. 在 **基础信息** > **凭证与基础信息** 页面，获取应用凭证 **App ID** 和 **App Secret**。
3. 调用[自建应用获取 app_access_token](https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/app_access_token_internal) 接口，通过应用凭证 App ID 和 App Secret 获取自建应用的`app_access_token`。
### 获取商店应用的 app_access_token
1. 获取 app_ticket。
1. 为商店应用配置事件订阅请求地址。
具体操作参见[配置请求地址](https://open.larksuite.com/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case)。完成配置后，Lark会每隔 1 小时向该地址自动推送最新的 `app_ticket`，应用根据接收到的 [app_ticket 事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/application-v6/event/app_ticket-events)来获取并保存`app_ticket`，以便后续使用。
2. （可选）调用[重新获取 app_ticket](https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/app_ticket_resend) 接口，触发Lark重新推送 `app_ticket`。
`app_ticket` 推送可能存在延迟，如果没有收到推送，可以使用该方式重新推送 `app_ticket`。
2. 获取应用凭证 App ID 和 App Secret。
1. 登录[开发者后台](https://open.larksuite.com/app/)，选择指定的自建应用。
2. 在 **基础信息** > **凭证与基础信息** 页面，获取应用凭证 **App ID** 和 **App Secret**。
3. 调用[商店应用获取 app_access_token](https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/app_access_token) 接口，通过应用凭证 App ID 和 App Secret、以及 app_ticket 获取商店应用的`app_access_token`。
### 获取商店应用的 tenant_access_token
请先获取并保存商店应用的 app_access_token，再获取商店应用的 tenant_access_token。
1. 获取 tenant_key。
`tenant_key`为租户在Lark上的唯一标识，用来换取对应的 `tenant_access_token`，也可以用作租户在应用里面的唯一标识，可以通过如下方式获取：
- 企业开通应用时，开放平台推送给应用的`tenant_key`数据，具体可参考[首次启用应用](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/application-v6/event/app-first-enabled)。
- 用户登录到小程序、H5 应用或者浏览器应用时，在用户的身份信息中获取。
2. 调用[商店应用获取 tenant_access_token](https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/auth-v3/auth/tenant_access_token) 接口，通过`app_access_token`和`tenant_key`获取商店应用的`tenant_access_token`。
### 获取 user_access_token
本章节以应用的网页应用功能为例介绍如何获取 user_access_token。
获取 user_access_token 的方式同时适用于企业自建应用和商店应用。
1. 登录[开发者后台](https://open.larksuite.com/app/)，选择指定应用。
2. 在 **开发配置** > **安全设置** 页面，配置重定向 URL。
你需要将实际发起 API 请求的服务端公网地址配置为应用的重定向 URL。重定向 URL 支持配置多个，只有在重定向 URL 列表中的 URL 在请求时才会通过开放平台的安全校验。
3. 调用[获取授权登录授权码](https://open.larksuite.com/document/common-capabilities/sso/api/obtain-oauth-code)接口，获取登录预授权码 `code`。
调用接口时需要使用应用凭证 App ID，你可以在应用详情页的 **基础信息** > **凭证与基础信息** 页面，获取应用凭证 **App ID**。
4. 调用[获取 user_access_token](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/authen-v1/oidc-access_token/create)接口，获取`user_access_token`。
同时可以获取到 Token 的有效期（expires_in 响应字段）。
5. （可选）调用[刷新 user_access_token](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/authen-v1/oidc-refresh_access_token/create)接口，刷新 `user_access_token`。
`user_access_token` 的有效期为两小时左右，过期后，需要刷新后再使用。
## 如何使用访问凭证（access_token）
使用访问凭证（access_token），需要在调用接口时将其填入到 HTTP 请求的 **请求头参数** 中，且该值需要增加 `Bearer<空格>` 前缀。
为了安全考虑， 请勿在应用前端使用访问凭证。请在应用服务端发起 API 访问请求。
每个 OpenAPI 文档中，均声明了该接口需要的访问凭证类型和获取方式。
例如，cURL 请求配置示例如下：
调用 API 的详细操作参见[调用 API](https://open.larksuite.com/document/ukTMukTMukTM/ukDNz4SO0MjL5QzM/get-)。
```Bash
curl --location --request GET 'https://open.larksuite.com/open-apis/contact/v3/departments/od-64242a18099d3a31acd24d8fce8dxxxx' \
--header 'Authorization: Bearer t-5888bcb7c421a695ca83c449caba5cxxxx' \
--header 'Content-Type: application/json; charset=utf-8'
```