# 获取调用凭证 Token


Token 是一种用于身份验证和授权的加密字符串，本质是服务端颁发的数字凭证，用于验证请求合法性并控制资源访问权限。智能服务调用的部分能力接口需要第三方传入应用级别鉴权 token 作为接口调用凭证，部分能力接口需要将应用级别 token 作为入参传入，这里提供应用级别 token 的获取方式。

# 接口说明

## 基本介绍

- 作用：获取应用级别鉴权 token，用于非用户授权的应用级能力接口调用入参传递。开发者通过传入应用的 app_id 和 app_secret，换取应用级别的 access_token，后续可作为调用其他 OpenAPI 接口的凭证。
- 业务场景：适用于服务端应用以自身身份调用智能服务开放平台 API 的场景，如后台数据查询、订单管理等不需要用户授权的操作。
- 前提条件：需要在智能服务开放平台完成应用创建，获取到 app_id 和 app_secret。
- 注意事项：
- app_secret 属于敏感信息，请妥善保管，切勿在客户端代码或公开环境中暴露。
- grant_type 参数请按照平台要求填写固定值 client_credential。

## 业务场景

client_token 用于不需要用户授权就可以调用的接口。

## 注意事项

- client_token 的有效时间为 2 个小时，重复获取 client_token 后会使上次的 client_token 失效（但有 5 分钟的缓冲时间，连续多次获取 client_token 只会保留最新的两个 client_token）。
- 禁止频繁调用 access-token 接口（频控规则：5 分钟内超过 500 次接口调用），建议在 token 过期前缓存复用。
- 获取的 access_token 有有效期限制（以 expires_in 字段返回的秒数为准），过期后需重新获取。

# 准备工作

## 前提条件

已在开发者后台注册并创建智能服务。

在控制台的开发 -> 开发配置页面中获取 AppID 和 AppSecret。

> 图片说明：图片展示的是豆包开发者平台中“开发配置”页面。左侧导航栏选中“开发配置”，右侧显示智能服务ID、AppID和AppSecret等信息，其中AppSecret部分被红色框突出显示。该图片与文档中获取AppID和AppSecret的前提条件部分相关，直观呈现了在开发配置页面获取AppID和AppSecret的操作位置，帮助开发者了解获取位置及信息展示情况。

## 说明

- 字段需保证安全存储：AppSecret 和 client_token 属于敏感信息，必须存储在服务端，禁止前端直接使用.
- 建议使用加密存储(如 Redis + AES 加密).
- 有效期管理：client_token 有效期通常为 2 小时，需设置定时任务刷新。

```json
{
    "code": 40001,
    "msg": "param error: invalid app_id",
    "log_id": "20231201120001ABCDEF654321",
    "data": null
}
```

# 接口基本信息

| 名称 | 描述 |
|-|-|
| HTTP Path | /api/token/v1/developer/get_client_token |
| HTTP Method | POST |
| Scope | 无需特殊 Scope |
| 权限要求 | 无需用户授权，使用应用自身凭证即可调用 |

## 请求头

| 名称 | 类型 | 必填 | 描述 |
|-|-|-|-|
| content-type | string | 是 | 固定值 "application/json" |

## 请求参数

### Body

| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|-|-|-|-|-|
| app_id | string | 是 | 应用ID，唯一标识一个三方应用。在智能服务开放平台创建应用后获取。 | tt07e3715e218c94OR |
| app_secret | string | 是 | 应用密钥，与 app_id 配对使用，用于验证应用身份。在智能服务开放平台应用详情页获取。 | clt.943da17996fb5ceb\*\*\*\*\*\* |
| grant_type | string | 是 | 授权认证类型，固定值为 client_credential。 | client_credential |

## 请求示例

cURL

Go

Java

Node.Js

```shell
curl -X POST 'https://api.doubao-dev.com/api/token/v1/developer/get_client_token' \
  -H 'content-type: application/json' \
  -d '{
    "app_id": "tt07e3715e218c94OR",
    "app_secret": "your_app_secret",
    "grant_type": "client_credential"
  }'
```

## 响应参数

| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|-|-|-|-|-|
| code | integer | 是 | 响应状态码，0 表示成功，非 0 表示失败。 | 0 |
| msg | string | 是 | 响应状态描述信息。 | success |
| log_id | string | 是 | 日志ID，用于问题排查时提供给技术支持。 | 20231201120000ABCDEF123456 |
| data | object | 是 | 响应数据对象，包含 token 等信息。详见下方 data 字段说明。 | - |

### data 字段说明

| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|-|-|-|-|-|
| access_token | string | 是 | 应用级别 token，后续调用其他 OpenAPI 接口时作为鉴权凭证传入。 | clt.943da17996fb5cecjT6HNKGqn\*\*\*\*\*\* |
| expires_in | integer | 是 | token 有效期，单位为秒。过期后需要重新调用本接口获取新的 token。 | 7200 |
| captcha | string | 否 | 验证码信息，特殊场景下返回。 | - |
| desc_url | string | 否 | 描述链接，特殊场景下返回。 | - |
| description | string | 否 | 附加描述信息。 | - |

## 响应示例

### 正常示例

```json
{
    "code": 0,
    "msg": "success",
    "log_id": "20231201120000ABCDEF123456",
    "data": {
        "access_token": "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******",
        "expires_in": 7200,
        "captcha": "",
        "desc_url": "",
        "description": ""
    }
}
```

### 异常示例

```json
{
    "code": 40001,
    "msg": "param error: invalid app_id",
    "log_id": "20231201120001ABCDEF654321",
    "data": null
}
```

## 错误码

| HTTP 状态码 | 错误码 | 描述 | 排查建议 |
|-|-|-|-|
| 200 | 0 | 请求成功 | - |
| 200 | 40001 | 参数错误 | 请检查请求参数是否完整、格式是否正确，确认 app_id、app_secret、grant_type 均已正确填写。 |
| 200 | 40002 | app_id 无效 | 请确认 app_id 是否正确，应用是否已在智能服务开放平台正常创建并启用。 |
| 200 | 40003 | app_secret 错误 | 请确认 app_secret 是否与 app_id 匹配，可在应用详情页重新获取。 |
| 200 | 42001 | 访问频率超限 | 请降低接口调用频率，建议缓存 access_token 并在过期前复用。 |