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

# 身份验证

> 了解如何使用 Cobo Auth 对 WaaS 服务的 API 请求进行身份验证。

<Tip>
  即刻安装 [Cobo WaaS Skill](/v2_cn/guides/overview/cobo-waas-skill)，在 Claude Code、Cursor 等 AI 开发环境中使用自然语言集成 WaaS API，显著提升开发效率 🚀
</Tip>

本文介绍如何使用 Cobo Auth 对 WaaS 服务的 API 请求进行身份验证。

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

您需要在请求头中提供 API Key、`Biz-Api-Nonce`（随机字符串）和 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：用作请求 nonce 的随机字符串。
* Biz-Api-Signature：API 签名。要了解如何计算 API 签名，请参阅[计算 API 签名](#calculate-the-api-signature)。

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

## API Key 和 API Secret

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

### API Key

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

API Key 与权限和钱包范围相关联，这些权限和范围定义了客户端可以执行的操作和可以访问的钱包。不同的 API Key 可以分配不同的权限和钱包范围，从而对客户端功能进行精细控制。
<Info>有关权限和钱包范围的更多详情，请参阅[权限和钱包范围](/v2_cn/guides/overview/permissions-and-scopes)。</Info>

### API Secret

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

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

* API Key 包含在 API 请求中，使 WaaS 服务能够识别客户端。使用前您需要在 Cobo Portal 上注册 API Key。更多信息，请参阅[注册 API Key](https://manuals.cobo.com/cn/portal/developer-console/create-api-key)。
* API Secret 用于生成每个 API 请求的签名。WaaS 服务验证签名以确认请求的真实性和防止篡改。

### 生成 API Key 和 API Secret

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

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

#### 使用 Cobo CLI

Cobo 命令行界面（CLI）是一种强大的开发者工具，旨在帮助您在集成 WaaS 2.0 API 时直接从命令行进行构建、测试和管理。

1. 使用以下命令安装 Cobo CLI：

   ```shell theme={null}
   # 使用 pip 安装 Cobo CLI（需要 Python 3.9 或更高版本）。
   pip install cobo-cli
   # 或者，您可以使用 Homebrew 安装 Cobo CLI。
   brew install cobo-cli
   # 测试安装是否成功
   cobo version
   ```

   有关 Cobo CLI 的系统要求，请参阅[安装 Cobo CLI](/v2_cn/developer-tools/cobo-cli/quick-start-guide#system-requirements)。

2. 使用 `keys generate` 命令生成 Ed25519 算法的密钥对，如下所示：

   ```shell theme={null}
   # 生成 API Key 和 API Secret
   cobo keys generate --key-type API
   ```

   生成的密钥将安全存储在您的配置文件中（默认：`~/.cobo/config.toml`）。有关此命令的更多信息，请参阅[密钥管理](/v2_cn/developer-tools/cobo-cli/key-management)。

#### 使用 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 Key](https://manuals.cobo.com/cn/portal/developer-console/create-api-key)。

<Warning>
  开发环境和生产环境使用**各自独立的 Cobo Portal 和 API Key**。在开发环境（`portal.dev.cobo.com`）注册的 API Key 无法用于生产环境的 API Host（`api.cobo.com`），反之亦然。使用错误环境的 API Key 将返回 HTTP 401 / 错误码 2024，错误信息为 `Your API key is not registered in this environment. Development and Production environments use separate API keys.`。各环境的 Host 和 Portal 地址请参阅[开发环境和生产环境](/v2_cn/guides/overview/environments)。
</Warning>

## Nonce

在 WaaS 2.0 身份验证中，Nonce 指请求头 `Biz-Api-Nonce` 的值，可以是任意随机字符串。

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

## 计算 API 签名

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

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

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

   | **字段** | **描述**                                   | **示例**                                                                  |
   | ------ | ---------------------------------------- | ----------------------------------------------------------------------- |
   | METHOD | HTTP 方法。                                 | `GET`                                                                   |
   | PATH   | API 端点。                                  | `/v2/transactions/transfer`                                             |
   | NONCE  | Nonce 值。该值必须与请求头 `Biz-Api-Nonce` 的值完全相同。 | `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 签名。