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

# Authentication

# 身份验证

AlphaFinance API使用API密钥进行身份验证，确保只有授权用户才能访问我们的数据服务。

## 获取API密钥

要获取API密钥，您需要：

1. 在 [AlphaFinance](https://alphafin.x-pai.com) 创建一个账户
2. 登录到 [控制台](https://alphafin.x-pai.com/dashboard)
3. 导航至"API密钥"部分
4. 点击"创建新密钥"按钮

您可以创建多个API密钥，为不同的应用使用不同的密钥，或在需要时轮换密钥。

<Warning>
  创建新密钥后，请立即将其安全地保存。出于安全考虑，我们只会显示一次完整的密钥值。
</Warning>

## 使用API密钥

在所有API请求中，您都需要包含API密钥。有两种方式可以做到这一点：

### 方法一：请求头（推荐）

将API密钥添加到HTTP请求头中：

```bash theme={null}
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519" \
  -H "X-API-KEY: your_api_key_here"
```

### 方法二：查询参数

将API密钥作为URL查询参数：

```bash theme={null}
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519&api_key=your_api_key_here"
```

<Note>
  出于安全考虑，我们强烈建议使用请求头方法传递API密钥，特别是在生产环境中。
</Note>

## 安全最佳实践

为保护您的API密钥和数据安全，请遵循以下最佳实践：

* **不要在客户端代码中嵌入API密钥**：前端JavaScript等客户端代码容易被查看，应通过后端服务器代理API请求。
* **使用环境变量**：将API密钥存储在环境变量中，而不是直接写入代码。
* **定期轮换密钥**：定期创建新密钥并废弃旧密钥，特别是在人员变动或安全事件后。
* **授予最小权限**：只分配完成任务所需的最小权限。
* **监控API使用情况**：定期检查API使用日志，及时发现异常活动。

## 速率限制

为确保服务质量，我们对API请求施加了速率限制。限制根据您的订阅计划而有所不同：

| 计划  | 速率限制      |
| --- | --------- |
| 入门版 | 100 请求/分钟 |
| 专业版 | 300 请求/分钟 |
| 企业版 | 定制限制      |

当您超过速率限制时，API将返回 `429 Too Many Requests` 状态码。响应头中的 `X-Rate-Limit-Remaining` 和 `X-Rate-Limit-Reset` 字段会告诉您剩余的请求次数和限制重置的时间。

## 错误响应

当身份验证出现问题时，您可能会收到以下错误：

### 401 Unauthorized

表示API密钥无效或未提供：

```json theme={null}
{
  "code": 401,
  "message": "Unauthorized: Invalid API key",
  "error": "invalid_key"
}
```

### 403 Forbidden

表示API密钥有效，但没有足够的权限访问请求的资源或操作：

```json theme={null}
{
  "code": 403,
  "message": "Forbidden: Insufficient permissions",
  "error": "insufficient_permissions"
}
```

## 示例代码

以下示例展示了如何在不同编程语言中使用API密钥：

<CodeGroup>
  ```python Python theme={null}
  import requests
  import os

  # 从环境变量获取API密钥
  api_key = os.environ.get("ALPHAFINANCE_API_KEY")

  url = "https://api.alphafin.x-pai.com/v1/stock/basic-info"
  params = {"symbol": "600519"}
  headers = {"X-API-KEY": api_key}

  response = requests.get(url, params=params, headers=headers)
  data = response.json()

  print(data)
  ```

  ```javascript JavaScript theme={null}
  // 使用Node.js环境变量
  const apiKey = process.env.ALPHAFINANCE_API_KEY;
  const url = 'https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519';

  fetch(url, {
    method: 'GET',
    headers: {
      'X-API-KEY': apiKey
    }
  })
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
  ```

  ```php PHP theme={null}
  <?php
  // 从环境变量获取API密钥
  $apiKey = getenv('ALPHAFINANCE_API_KEY');
  $url = 'https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519';

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-KEY: ' . $apiKey
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## 后续步骤

一旦您设置好身份验证，您可以开始探索我们丰富的API功能：

* [股票基本信息](/api-reference/stock/basic-info)
* [日K行情数据](/api-reference/market/daily)
* [财务报表数据](/api-reference/financials/income-statement)

如需更多支持，请查看我们的[常见问题](/faq)或[联系支持团队](mailto:support@alphafin.x-pai.com)。