> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/payments/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份验证

本文介绍如何对 Cobo 支付服务的 API 请求进行身份验证。

为确保您加密资产的安全访问，Cobo 支付服务要求您使用 EdDSA 签名对每个 API 请求进行签名（可公开访问的 API 操作除外）。

您需要在请求头中提供 API Key、随机数和 API 签名：

```
headers = {
  "Biz-Api-Key": {YOUR_API_KEY}.hex(),
  "Biz-Api-Nonce": {Nonce},
  "Biz-Api-Signature": {YOUR_API_SIGNATURE}.hex(),
}
```

* Biz-Api-Key：用于请求的 API Key。更多详情，请参阅 [API Key](#api-key)。
* Biz-Api-Nonce：随机数。随机数是以毫秒为单位的当前 Unix 时间戳。
* Biz-Api-Signature：API 签名。要了解如何计算 API 签名，请参阅[计算 API 签名](#calculate-the-api-signature)。

如果您使用 Cobo 的 Payments API SDK，您只需提供 API Secret，因为 SDK 会为您处理其余步骤。

## API Key 和 API Secret

为了实现客户端与 Cobo 支付服务之间的安全通信和身份认证，我们使用了 API Key 和 API Secret 机制。该机制依赖于加密密钥对来验证客户端的身份和请求的完整性。

### API Key

API Key 是加密密钥对中的公钥。它用于识别发起 API 请求的客户端。

### API Secret

API Secret 是密钥对中的私钥。它用于签署 API 请求，保证其真实性和完整性。API Secret 是高度敏感的数据，请务必妥善保管并采取严格的安全措施。

API Key 和 API Secret 共同确保了客户端与 Cobo 支付服务端的通信安全：

* API Key 包含在 API 请求中，使 Cobo 支付服务能够识别客户端。使用前您需要在 Cobo Portal 上注册 API Key。
* API Secret 用于生成每个 API 请求的签名。Cobo 支付服务验证签名以确认请求的真实性和防止篡改。

### 生成 API Key 和 API Secret

本节介绍如何使用 Ed25519 算法生成 API Key 和 API Secret。您也可以使用其他支持 Ed25519 算法的工具进行生成。

公钥将用作 API Key，私钥将用作 API Secret。

#### 使用 OpenSSL

在终端窗口中，运行以下 OpenSSL 命令生成 Ed25519 算法的密钥对：

```shell theme={null}
openssl genpkey -algorithm ed25519 -out private_key.pem

openssl pkey -in private_key.pem -pubout -out public_key.pem

echo "Private Key (Hex):"
openssl pkey -in private_key.pem -text | grep 'priv:' -A 3 | tail -n +2 | tr -d ':\n ' && echo

echo "Public Key (Hex):"
openssl pkey -pubin -in public_key.pem -text | grep 'pub:' -A 3 | tail -n +2 | tr -d ':\n ' && echo

```

您将看到类似以下示例的输出：

```
Private Key (Hex):
06f78882576ec0e05b1e51a33548da7e8cf958c190ba96be77b1c671f98a2b5f
Public Key (Hex):
5987dedc180167b7ab1d27e6009e5065d10d764cd85d7b64f8c968ca40326e28
```

使用 `Private Key (Hex)` 作为您的 API Secret，使用 `Public Key (Hex)` 作为您的 API Key。

#### 使用 Python 库

1. 安装 `PyNaCl` Python 库。

   在终端窗口中，运行以下命令：

   ```shell theme={null}
   pip install PyNaCl
   ```

2. 生成密钥对。
   从 Python 库导入函数生成基于 Ed25519 算法的密钥对，如下所示：

   ```python theme={null}
   from nacl.signing import SigningKey
   # 创建密钥对。
   sk = SigningKey.generate()
   # 打印十六进制格式的私钥
   print("私钥:", sk.encode().hex())
   # 打印十六进制格式的公钥
   print("公钥:", sk.verify_key.encode().hex())
   ```

### 注册 API Key

生成 API Key 后，您需要在 Cobo Portal 上注册密钥。要了解如何注册 API Key，请参阅[发送您的第一个 API 请求](/payments/cn/developer-tools/get-started-with-api#注册-api-key)。

## 随机数

随机数为 Unix 时间戳格式的当前时间，以毫秒为单位。

<a name="calculate-the-api-signature" />

## 计算 API 签名

以下步骤介绍如何计算 API 签名。

1. 首先，基于您的请求拼接出一个字符串，如下所示：

   str\_to\_sign = `{METHOD}|{PATH}|{TIMESTAMP}|{PARAMS}|{BODY}`

   | **字段**    | **描述**                              | **示例**                                                                  |
   | --------- | ----------------------------------- | ----------------------------------------------------------------------- |
   | METHOD    | HTTP 方法。                            | `GET`                                                                   |
   | PATH      | API 端点。                             | `/v2/payments/topup/address`                                            |
   | TIMESTAMP | 以毫秒为单位的当前 Unix 时间戳。该值必须与请求头中的随机数相同。 | `1718587017026`                                                         |
   | PARAMS    | （如有）查询参数。                           | `chain_id=ETH&limit=10  `                                               |
   | BODY      | （如有）原始请求包体的字符串格式。                   | `{"name":"Default","wallet_subtype":"Asset","wallet_type":"Custodial"}` |

2. 使用 `hashlib` 库对字符串进行两次 SHA-256 哈希，如下所示：

   ```python theme={null}
   import hashlib
   content_hash = hashlib.sha256(hashlib.sha256(str_to_sign.encode()).digest()).digest()
   ```

3. 使用 API Secret 对字符串进行签名，如下所示：

   ```python theme={null}
   from nacl.signing import SigningKey

   # 创建 Ed25519 签名密钥。将 `api_secret` 替换为您的 API Secret
   sk = SigningKey(bytes.fromhex(api_secret))
   # 签署哈希后的消息
   signature = sk.sign(content_hash).signature.hex()
   ```

现在您已经计算出了一个 API 签名。