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

# 身份验证

Sorsa API 使用 API 密钥验证请求。密钥可完整访问你的账号和配额，请像密码一样保护它。

***

## 身份验证的工作方式

向 Sorsa API 发送的每个请求都必须在 `ApiKey` 请求头中包含 API 密钥。HTTP 请求头名称不区分大小写；请使用此处给出的拼写，并保持密钥值完全不变。

```text theme={null}
ApiKey: your_api_key_here
```

如果请求头缺失、拼写错误或密钥无效，API 会返回错误（见下方[故障排查](#troubleshooting)）。

**请求示例**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**对于 POST 端点**，还需要包含 `Content-Type` 请求头：

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query": "bitcoin", "order": "popular"}'
```

> **提示：** 可以使用 [API Playground](https://api.sorsa.io/playground)测试密钥，无需编写代码。

***

## 请求要求

每次 API 调用都必须满足以下要求：

**仅支持 HTTPS。** 所有请求都必须使用 `https://`。纯 HTTP 请求会被拒绝。

**ApiKey 请求头。** 每个请求都必须包含。无需 OAuth、Bearer 令牌，也不支持查询参数身份验证。

**Content-Type 请求头。** POST 请求必需。将其设为 `application/json`，并通过 JSON 请求体传递参数。

**HTTP 方法。** 不同操作使用 GET 或 POST。[API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)列出了各端点所用的方法。

***

## 管理 API 密钥

**查找密钥。** 当前密钥显示在[控制台概览页](https://api.sorsa.io/overview)。新账号包含 100 次免费请求，无需绑定银行卡即可立即使用第一个密钥。

**创建或删除密钥。** 要生成新密钥或撤销现有密钥，请前往控制台中的 [API Keys](https://api.sorsa.io/overview/keys) 页面。

**监控用量。** 可通过[用量统计](https://api.sorsa.io/overview/usage)页面，或以编程方式调用 `GET /key-usage-info`，追踪请求历史和剩余配额。

> **重要：** 删除或替换密钥后，仍使用旧密钥的应用会立即收到 `401 Unauthorized` 错误。撤销密钥之前，请先更新集成。

***

## 安全最佳实践

**不要在客户端代码中暴露密钥。** 不要从浏览器、移动应用或任何前端环境直接调用 Sorsa API，否则密钥会暴露在浏览器开发者工具、网络日志和源代码中。始终通过自己的后端服务器转发请求。

**使用环境变量。** 将密钥存储在 `.env` 文件或平台的机密管理服务中，例如 AWS Secrets Manager、Vercel Environment Variables、Railway Variables 等。不要把密钥硬编码在源文件中。

**不要将密钥纳入版本控制。** 把 `.env` 添加到 `.gitignore`。不要将 API 密钥提交至 GitHub、GitLab 或 Bitbucket 的公开或私有仓库。

**密钥泄露后立即更换。** 如果不慎在代码提交、截图或公开论坛中泄露密钥，请前往 [API Keys](https://api.sorsa.io/overview/keys) 页面，删除已泄露密钥并生成新密钥。旧密钥会立即失效。

***

<a id="troubleshooting" />

## 故障排查

**401 Unauthorized**

`ApiKey` 请求头缺失、名称拼写错误，或密钥已被删除或本身无效。检查名称确实是 `ApiKey`，而不是 `Api-Key` 或 `Authorization`。

**403 Forbidden**

密钥有效，但订阅已过期或月度请求配额已耗尽。通过[控制台](https://api.sorsa.io/overview)或调用 `GET /key-usage-info` 检查剩余次数。

**429 Too Many Requests**

请求速度超过上限（所有套餐均为每秒 20 次）。在调用之间加入短暂退避并重试。详情和重试策略请参阅[速率限制](https://docs.sorsa.io/zh-Hans/rate-limits)。

**浏览器中的 CORS 错误**

出现 CORS 错误通常意味着你正在通过前端 JavaScript 调用 API。Sorsa API 仅面向服务端使用。请将 API 调用移至后端服务或无服务器函数。

***

## 后续步骤

* [速率限制](https://docs.sorsa.io/zh-Hans/rate-limits)：了解请求配额和重试策略
* [密钥用量信息](https://docs.sorsa.io/zh-Hans/api-reference/technical-endpoints/api-key-usage)：以编程方式检查余额
* [API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)：探索所有可用端点