# 创建授权书免登申请会话

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=CreateRightAuthLetterApplicationSession&Version=2024-01-01`

为指定商业 IP 和被授权方创建授权书免登申请会话，返回申请链接、会话 ID 及访问截止时间。

> **说明：回调通知协议**
>
> 配置 *Callback* 后，平台通过 HTTP POST 发送申请结果通知。
>
> * 请求头 `X-Ark-Auth-Letter-Timestamp` 为 UTC Unix 秒字符串。
> * 请求头 `X-Ark-Auth-Letter-Signature` 的格式为 `v1=<signature>`，其中 `<signature>` 是 64 位小写十六进制 HMAC-SHA256 签名。
> * 签名消息为 `<timestamp>.<原始 HTTP 请求体字节>`，密钥为 *Callback.Secret* 经 Base64URL 解码后的 32 字节。
> * 建议结合服务端时钟校验 *timestamp* 的可接受时间窗口，避免重放攻击。
> * 请求体包含必选字段 *SessionId*、*Status* 和可选字段 *ApplicationId*。*Status* 仅可能为 `SUCCEEDED` 或 `FAILED`。
> * 按 *SessionId* 和 *Status* 幂等处理通知，并在可靠保存通知后返回 HTTP 2xx，建议在 3 秒内完成。平台对部分发送失败最多发送 4 次。
> * 回调可能重复或未送达。验签成功后仍需调用 *GetRightAuthLetterApplicationSession* 获取最新状态和下载地址。

> **说明：错误码**
>
> * HTTP 400，`MissingParameter.*`，`The required parameter <Parameter> is missing.`：缺少必填参数。补齐参数后重新请求。
> * HTTP 400，`InvalidParameter.*`，`The specified parameter <Parameter> is invalid.`：参数值不合法。按参数说明修正后重新请求。
> * HTTP 500，`InternalError`，`The request has failed due to an unknown error.`：服务内部错误。不要自动重试创建请求，以免产生重复申请；记录响应中的 *RequestId* 并联系技术支持。

> **注意：避免重复创建**
>
> 每次调用本接口都会创建新的申请记录和链接。请求超时时不要自动连续重试；确需重新创建时，只向用户提供新链接。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**IpId** `string` `必选` | 商业 IP ID

本次授权书申请对应的单个商业 IP ID。应传入支持授权书申请且当前账号有权使用的 IP ID，不得包含首尾空白；UTF-8 编码后最多 64 字节。

**AuthorizedSubject** `object` `必选` | 被授权方

被授权方主体信息。当前仅需填写 *AuthorizedSubject.SubjectName*。

**SubjectName** `string` `必选` | 被授权方名称

`AuthorizedSubject.SubjectName`

授权书中的真实被授权方主体名称，不会从签名账号的实名资料自动取值；不得为空或仅包含空白字符。

**ProjectName** `string` `默认值 default` | 所属项目

资源所属的项目名称，用于确定本次申请归属的资源项目，不是用户在申请表中填写的作品或商业项目标题。传入时不得为空，UTF-8 编码后最多 255 字节。

**Callback** `object` | 回调配置

申请结果回调配置。启用后，平台在申请成功或失败时向指定地址发送通知；通知不包含授权书文件，收到后需查询会话获取最新状态和下载地址。

> **说明**
>
> 传入 *Callback* 时，必须同时提供 *Callback.URL* 和 *Callback.Secret*。平台不发送处理中或授权书作废通知；未提交即过期的申请可能收到状态为 `FAILED` 的通知，但查询状态为 `EXPIRED`。回调可能重复或未送达，请以查询接口返回的最新状态为准。

**URL** `string` `必选` | 回调地址

`Callback.URL`

客户接收申请结果通知的公网 HTTPS 地址，最多 2048 个字符。地址应使用默认端口或 `443`，不得包含用户名、密码或 URL 片段，也不应发生重定向。

**Secret** `string` `必选` | 回调密钥

`Callback.Secret`

用于验证回调签名的共享密钥。应由客户生成 32 字节安全随机数，并编码为不含末尾等号的 43 字符 Base64URL 字符串；不得记录日志或返回给客户端。

> **注意**
>
> 验签时，先将 *Secret* 解码为 32 字节密钥，再对 `<timestamp>.<原始 HTTP 请求体字节>` 计算 HMAC-SHA256。不要对解析后的 JSON 重新序列化后验签。

## 响应参数

**SessionId** `string` | 申请会话 ID

本次申请会话的唯一标识，用于调用 *GetRightAuthLetterApplicationSession* 查询状态和识别回调通知。应直接保存返回值，不得自行生成或修改。

**ApplicationURL** `string` | 免登申请链接

包含访问凭证的完整免登申请链接。应原样提供给指定用户，不得自行拼接或修改。

> **注意**
>
> 该链接仅在创建成功时返回，后续查询不会补发。链接包含访问凭证，请妥善保存，仅发送给指定用户，不要公开或写入普通日志。

**FirstAccessExpireAt** `integer` | 首次访问截止时间

用户首次成功进入申请页面的截止时间，为 UTC Unix 时间戳，单位为秒。客户服务端查询会话状态不计为访问申请页面。

> **说明**
>
> 当前默认首次访问时限为创建后 10 分钟。请以接口返回的时间为准，不要在客户端固定该时限。

**SessionExpireAt** `integer` | 会话访问截止时间

免登申请入口的总访问截止时间，为 UTC Unix 时间戳，单位为秒。该时间从会话创建时开始计算，不会在用户首次打开链接后重新计时。

> **说明**
>
> 当前默认总访问时限为创建后 24 小时。请以接口返回的时间为准；服务端配置热更新后，实际访问有效性以平台校验结果为准。