字节API鉴权方法

目前提供 token 和 signature 两种鉴权方式，选择一种就可以完成鉴权。推荐使用较简单的 token 鉴权。

appid、access_token 和 secret_key 由平台分配，通过控制台创建应用获得，创建应用并开通服务文档。

Token 鉴权 #

在连接建立时，须在发送的 GET 或 POST 请求中加上鉴权相关的 Authorization header。如下面示例：

GET /api/v2/asr HTTP/1.1
Host: openspeech.bytedance.com
Accept: */*
User-Agent: curl/7.54.0
Authorization: Bearer; FYaWxBiJnuh-0KBTS00KCo73rxmDnalivd1UDSD-W5E=

Copy and SaveGet Link

Authorization header 的格式是 Bearer; {token}

Bearer：授权方法名
token: 控制台获取的 token

注意授权方法名和 token 之间使用 ; 分割。

Signature 鉴权 #

相比于 token 鉴权，signature 还需在 Authorization header 中加入 access_token、mac、h 等信息。如以下示例：

GET /api/v2/asr HTTP/1.1
Host: openspeech.bytedance.com
Accept: */*
User-Agent: curl/7.54.0
Authorization: HMAC256; access_token="fake_token"; mac="akY93zOmVnV6IFa2RYqedLJXqYmro_9GQmKEKanb8zw="; h="accept,User-Agent"

Copy and SaveGet Link

Authorization header 由四个部分组成：

HMAC256：授权方法名
fake_token: 控制台获取的 token
mac: 消息验证码，使用 HMAC-SHA256 算法生成的签名串，再经过 base64 url 编码，其中 base64 编码后的值是否带有填充的 “=” 并不影响判断结果。生成签名串的方法见下一节。
h:（可选）自定义需要签名的 header 列表，列表中的 header 都用 ,分割

生成签名串 #

使用 HMAC-SHA256 算法对输入的字符串用 secret_key 作为 key进行加密,然后使用 base64 url 对结果进行编码。
待加密字符串分为三个部分：

HTTP 请求行或者状态行
Headers，默认使用 Host 加密，但如果指定了 h，则根据 h 添加
Body（如果存在）

示例模版如下（添加了换行符以提高可读性，输入字符串的实际换行符使用 \n 进行转义）：

<Proto> <StatusCode> <StatusMessage>\n
<Header1>\n
<Header2>\n
...\n
<Body>

Copy and SaveGet Link

【注】：Headers 必须按照自定义 header h 里指定的顺序加入待加密字符串。如果指定了 header 但是请求中找不到，server 端会返回 error。如果 header 被多次指定，则必须被多次添加到待加密字符串中。
【注】：WebSocket 的签名计算是有 body 的，需加上 body 数据进行签名计算。

示例 #

若原始建连请求为：

GET /api/v2/asr HTTP/1.1
Host: openspeech.bytedance.com
User-Agent: Python/3.9 websockets/8.1

Copy and SaveGet Link

假设 secret_key 为下面以 16 进制表示的二进制串(该二进制串对应的原始文本为"super_secret_key")：

73 75 70 65 72 5f 73 65 63 72 65 74 5f 6b 65 79

指定 h 为 "User-Agent"，且假定 body 数据为 “xxxxxxxxxx"，则原始待加密字符串为：

GET /api/v2/asr HTTP/1.1
Python/3.9 websockets/8.1
xxxxxxxxxx

Copy and SaveGet Link

经过 HMAC-SHA256 加密以及 base64 url 编码后，计算得出 mac 为：“j_jmd9Fjy4pfI7mKIqNVXqZ7TmG6oEkMPF8ImdFniHQ”。
假定 access_token 为 “fake_token” 所以最终的建连请求为：

GET /api/v2/asr HTTP/1.1
Host: openspeech.bytedance.com
User-Agent: Python/3.9 websockets/8.1
Authorization: HMAC256; access_token="fake_token"; mac="j_jmd9Fjy4pfI7mKIqNVXqZ7TmG6oEkMPF8ImdFniHQ"; h="User-Agent"