身份认证 · Alaya NeW Cloud Docs

九章智算云 OpenAPI 采用 HMAC-SHA256 签名认证机制。所有 OpenAPI 请求必须携带合法的 Authorization 请求头，否则服务器将拒绝处理请求。

本文介绍完整的认证流程，包括 AccessKey 获取、待签名字符串构造、签名计算、请求头组装以及常见鉴权错误的排查方法。

认证机制特点

身份认证：验证请求来源是否合法，确保仅持有有效 AccessKey 的调用方才能访问资源。
数据完整性：防止请求内容在传输过程中被篡改，签名覆盖请求方法、路径及时间戳等核心要素。
防重放攻击：签名包含毫秒级时间戳，仅在有效时间窗口（±5 分钟）内生效，过期请求将被拒绝。
密钥安全：SecretKey仅用于客户端本地签名运算，不参与网络传输，降低泄露风险。

请求头格式

Authorization 请求头的格式如下：

Authorization: alayanew-HMAC-SHA256 {ak}:{timestamp}:{signature}

字段	类型	说明	示例
Scheme	String	固定值	`alayanew-HMAC-SHA256`
ak	String	Access Key 标识	`ak_x9k2m8p4q1w3e5r7t9y0u2i4o6a8s0d2`
timestamp	Long	请求时间戳（毫秒，13 位）	`1709500800000`
signature	String	HMAC-SHA256 签名（十六进制小写）	`a1b2c3d4e5f6...`

获取 AccessKey

AccessKey 由 AccessKey ID（简称 ak）和 AccessKey Secret（简称 sk）组成：

AccessKey ID（ak）：访问密钥的唯一公开标识符，用于标识调用者身份。
AccessKey Secret（sk）：访问密钥的密文部分，用于对 API 请求进行 HMAC-SHA256 签名，以验证请求的真实性和完整性，请须妥善保管。

登录九章智算云控制台，点击产品中心，切换至客户中心/权限管理/访问管理菜单项，进入AccessKey列表页面。
单击创建 AccessKey按钮，在弹出的对话框中输入AccessKey 名称，并配置过期时间（留空表示永不过期），单击确定按钮，系统自动生成 AccessKey。

获取`Authorization`请求头

按照以下拼接规范，生成用于计算签名的原始字符串（StringToSign）。

StringToSign = Timestamp + "|" + HTTPMethod + "|" + URI

字段	规则	示例
Timestamp	当前 Unix 毫秒时间戳（13 位），参与签名计算；请求时间需在服务端当前时间 ±5 分钟内。	`1709521600000`
HTTPMethod	请求方法，转换为大写后参与签名。	`POST`
URI	请求路径，包含 Context Path，不包含协议、域名、端口及查询参数，仅使用 Path 部分参与签名。	`/api/osm/v1/cci/instance/list`

字符串的示例如下：

1709521600000|POST|/api/osm/v1/cci/instance/list

使用sk对待签名字符串进行HMAC-SHA256运算，并将结果转换为十六进制字符串。

signature = HexEncode(HMAC-SHA256(sk, StringToSign))

签名（signature）辅助函数如下所示。

import hmac, hashlib, time

ACCESS_KEY = "ak_xxx"
SECRET_KEY = "sk_xxx"

def generate_authorization(method: str, uri: str) -> str:
    timestamp = int(time.time() * 1000)
    string_to_sign = f"{timestamp}|{method.upper()}|{uri}"
    signature = hmac.new(
        SECRET_KEY.encode(), string_to_sign.encode(), hashlib.sha256
    ).hexdigest()
    return f"alayanew-HMAC-SHA256 {ACCESS_KEY}:{timestamp}:{signature}"

public static String generateAuthorization(String method, String uri) throws Exception {
    long timestamp = System.currentTimeMillis();
    String stringToSign = timestamp + "|" + method.toUpperCase() + "|" + uri;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(SECRET_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] bytes = mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8));
    StringBuilder sb = new StringBuilder();
    for (byte b : bytes) sb.append(String.format("%02x", b));
    return String.format("alayanew-HMAC-SHA256 %s:%d:%s", ACCESS_KEY, timestamp, sb);
}

func generateAuthorization(method, uri string) string {
    timestamp := time.Now().UnixMilli()
    stringToSign := fmt.Sprintf("%d|%s|%s", timestamp, strings.ToUpper(method), uri)
    h := hmac.New(sha256.New, []byte(secretKey))
    h.Write([]byte(stringToSign))
    signature := hex.EncodeToString(h.Sum(nil))
    return fmt.Sprintf("alayanew-HMAC-SHA256 %s:%d:%s", accessKey, timestamp, signature)
}

根据请求头格式（alayanew-HMAC-SHA256 {ak}:{timestamp}:{signature}），拼接生成Authorization请求头参数，示例如下所示。

alayanew-HMAC-SHA256 ak_xxx:1752645600123:9f1b8e5b87b3c8b92b65c9f43f83cdbb3d0a9d9d42d3fbe1b9e4b3b8b3c6d7a1

说明

每次发起API请求时，均需基于当前时间戳、HTTP方法和请求路径实时生成Authorization请求头。签名仅对当前请求有效，请勿复用、缓存或硬编码历史签名。
所有 OpenAPI 请求均应使用 HTTPS 协议，以保障鉴权信息和业务数据在传输过程中的机密性与完整性，防止数据被窃听或篡改。

生成 Authorization 请求头后，将其添加到HTTP请求头中即可完成请求认证。

下面以查询CCI实例列表接口为例，展示完整的curl请求示例。

curl -X GET 'https://api.alayanew.com/api/osm/v1/cci/instance/list?pageNo=1&pageSize=20' \
  -H 'accept: application/json' \
  -H 'Authorization: alayanew-HMAC-SHA256 ak_xxx:1752645600123:9f1b8e5b87b3c8b92b65c9f43f83cdbb3d0a9d9d42d3fbe1b9e4b3b8b3c6d7a1'

请求成功后，服务器返回JSON格式的实例列表数据；若认证失败，则返回对应错误码及提示信息。

鉴权错误码

当认证信息不合法或请求异常时，服务器返回以下错误码：

错误码	HTTP 状态	说明	排查建议
40001	401 Unauthorized	缺少 Authorization 请求头或格式错误	检查请求头是否包含 Authorization 字段，且格式符合 `alayanew-HMAC-SHA256 {ak}:{timestamp}:{signature}`。
40002	401 Unauthorized	时间戳格式错误或超出有效窗口（±5 分钟）	确认服务器时间与标准时间同步；检查时间戳是否为毫秒级 13 位数字。
40003	401 Unauthorized	签名验证失败	核对待签名字符串构造是否正确（顺序：Timestamp\|HTTPMethod\|URI）；确认`sk`未误用为`ak`；检查`URI`是否包含域名或查询参数。
40004	403 Forbidden	Access Key已禁用	登录控制台检查该AccessKey状态，如已禁用则启用或重新创建。
40005	403 Forbidden	Access Key已过期	该 AccessKey 已超过配置的过期时间，请重新创建新的 AccessKey。
40006	401 Unauthorized	Access Key 不存在	检查请求中的`ak`是否正确，确认未误用`sk`或其他标识符。
40007	503 Service Unavailable	OpenAPI 服务未启用或认证模块不可用	请联系平台管理员确认OpenAPI服务状态及认证模块配置。

认证机制特点

请求头格式

获取 AccessKey

获取Authorization请求头

鉴权错误码

获取`Authorization`请求头