预装版 UI 鉴权 ​

预装版 UI 使用 /api/grant/code 返回的 code 初始化 iframe。AK/SK 签名和获取 code 的请求留在服务端，浏览器只接收初始化所需的结果。

code 获取与使用边界 ​

问题结论
这个 code 用在哪里只用于预装版 UI 前端初始化 AipptIframe.show
谁来获取 code接入方服务端使用 AK/SK 签名请求 /api/grant/code
前端是否可以直接计算签名不可以，Secret Key 不应暴露到浏览器
是否可以复用拼装版 API 的 token不可以，拼装版 API 使用 token，预装版 UI 使用 code

获取 code 前检查 ​

检查项要求
开放平台凭证已获取 App Key 和 Secret Key
用户标识已确定接入方用户唯一标识 uid
获取位置code 必须由接入方服务端获取
使用位置code 只用于前端初始化 AipptIframe.show

注意

预装版 UI 使用 /api/grant/code 返回的 code，拼装版 API 使用 token。两者不要混用。

鉴权链路 ​

  1. 接入方服务端构造待签字符串。
  2. 使用 Secret Key 计算 x-signature。
  3. 调用 GET /api/grant/code 获取 code。
  4. 前端调用 AipptIframe.show，传入 appkey、code 和 channel。
  5. code 失效时，前端重新向接入方服务端申请新的 code。

凭证边界 ​

凭证获取接口使用位置适用接入方式
token/api/grant/token拼装版 API 请求 Header拼装版 API
code/api/grant/codeAipptIframe.show 初始化参数预装版 UI

如果同一个业务同时接入多种方式，建议在服务端拆分不同的授权方法，避免把 token、code、otp_code 作为同一种“登录凭证”透传。

签名规则 ​

字段取值
请求方法GET
签名路径/api/grant/code/
待签字符串GET@/api/grant/code/@{timestamp}
签名算法HmacSHA1 后进行 Base64 编码

Node.js 服务端完整示例 ​

ts
import CryptoJS from 'crypto-js'

const API_ORIGIN = 'https://co.aippt.cn'
const apiKey = process.env.AIPPT_API_KEY!
const apiSecret = process.env.AIPPT_API_SECRET!

function createSignature(path: string, timestamp: number) {
  const apiUri = path.endsWith('/') ? path : `${path}/`
  const stringToSign = `GET@${apiUri}@${timestamp}`
  const hash = CryptoJS.HmacSHA1(stringToSign, apiSecret)
  return CryptoJS.enc.Base64.stringify(hash)
}

export async function getAipptCode(uid: string, channel = '', type = '') {
  const path = '/api/grant/code'
  const timestamp = Math.floor(Date.now() / 1000)
  const signature = createSignature(path, timestamp)

  const url = new URL(path, API_ORIGIN)
  url.searchParams.set('uid', uid)
  url.searchParams.set('channel', channel)
  if (type) url.searchParams.set('type', type)

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'x-api-key': apiKey,
      'x-timestamp': String(timestamp),
      'x-signature': signature
    }
  })

  const result = await response.json()
  if (!response.ok || result.code !== 0) {
    throw new Error(result.msg || `获取 code 失败：${response.status}`)
  }

  return {
    code: result.data.code as string,
    expiresIn: result.data.time_expire as number,
    apiKey: result.data.api_key as string,
    uid: result.data.uid as string
  }
}

其他语言签名片段 ​

以下示例只负责生成 x-signature。实际请求时还需要同时传入 x-api-key 和同一个 timestamp。

Java ​

java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

String apiSecret = "<apiSecret>";
long timestamp = System.currentTimeMillis() / 1000;
String stringToSign = "GET@/api/grant/code/@" + timestamp;

Mac mac = Mac.getInstance("HmacSHA1");
mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA1"));
String signature = Base64.getEncoder().encodeToString(
    mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8))
);

Python ​

python
import base64
import hashlib
import hmac
import time

api_secret = "<apiSecret>"
timestamp = int(time.time())
string_to_sign = f"GET@/api/grant/code/@{timestamp}"
signature = base64.b64encode(
    hmac.new(api_secret.encode(), string_to_sign.encode(), hashlib.sha1).digest()
).decode()

Go ​

go
package main

import (
    "crypto/hmac"
    "crypto/sha1"
    "encoding/base64"
    "fmt"
    "time"
)

func main() {
    apiSecret := "<apiSecret>"
    timestamp := time.Now().Unix()
    stringToSign := fmt.Sprintf("GET@/api/grant/code/@%d", timestamp)

    mac := hmac.New(sha1.New, []byte(apiSecret))
    mac.Write([]byte(stringToSign))
    signature := base64.StdEncoding.EncodeToString(mac.Sum(nil))
    fmt.Println(signature)
}

PHP ​

php
<?php
$apiSecret = '<apiSecret>';
$timestamp = time();
$stringToSign = 'GET@/api/grant/code/@' . $timestamp;
$signature = base64_encode(hash_hmac('sha1', $stringToSign, $apiSecret, true));
?>

请求 Header 中的 x-timestamp 必须与待签字符串里的 {timestamp} 保持一致。

获取 code ​

业务流程图 ​

接口说明 ​

接口描述第三方用户在前端打开预装版 UI iframe 时，需要通过第三方服务端调用 AIPPT API 接口申请访问的授权码（x-code）。
接口地址/api/grant/code请求方式GET
权限校验是请求参数json

请求参数 ​

请求示例 ​

bash
curl --location 'https://co.aippt.cn/api/grant/code?uid=1&type=&channel=' \
--header 'x-api-key: <apiKey>' \
--header 'x-timestamp: 1696821929' \
--header 'x-signature: <signature>'

<signature> 必须按以下签名规则实时计算，不要复用示例值。

响应内容 ​

响应示例 ​

json
{
  "code": 0,
  "data": {
    "api_key": "api_key",
    "uid": "1",
    "code": "429738a59f91d6977843fd1c893bc66b",
    "time_expire": 86400
  },
  "msg": "ok"
}

前端使用方式 ​

js
await AipptIframe.show({
  appkey: '<apiKey>',
  channel: '',
  code: '<code>',
  container: document.getElementById('container'),
  onMessage(eventType, data) {
    console.log(eventType, data)
  }
})

过期处理 ​

场景建议处理
初始化提示 code 过期接入方前端重新请求自己的服务端，由服务端重新获取 code。
页面刷新或重新打开 iframe建议重新申请 code，不要长期复用旧值。
需要自定义页面入口鉴权成功后继续阅读 UI 配置。

状态码 ​

鉴权完成后打开 iframe ​

  • 阅读 UI 接入，完成 iframe 最小可用接入。
  • 阅读 UI 配置，配置默认页面、场景鉴权、自定义创建和下载模式。