> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-api/shen-fen-yan-zheng.md).

# 身份验证

了解如何对 Oxylabs Web API 端点的请求进行身份验证。

Oxylabs Web API 使用 **API 密钥作为 Bearer Token** 进行身份验证。发送到 API 的每个 HTTP 请求都必须在 `Authorization` 请求标头中包含你的 API 密钥。

```http
Authorization: Bearer YOUR_API_KEY
```

{% hint style="warning" %}
**Bearer 方案是必需的。** API 后端会解析 `Authorization` 标头中的 `Bearer` 前缀。标准 HTTP Basic Authentication（`Authorization: Basic ...`）不接受任何 `/v1/scrape` 或 `/v1/search` 请求，并会返回 `401 Unauthorized` 状态码。
{% endhint %}

要验证你的凭据，可以提交一个最小搜索查询：

```bash
curl https://webapi.oxylabs.io/v1/search \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{"query": "oxylabs"}'
```

## 获取密钥

1. 登录到 [Oxylabs 控制台](https://dashboard.oxylabs.io).
2. 创建一个 **Web API** 实例。
3. 在该实例上生成 API 密钥。
4. 将其导出到应用程序读取的位置（例如你的操作系统终端或项目工作区的 CLI 终端）：

```bash
export OXYLABS_WEB_API_KEY=your_api_key_here
```

## 故障排查 `401 Unauthorized` 错误

身份验证失败会返回 HTTP `401` 状态，不带 JSON 响应体。状态码本身表明该请求已被拒绝。

<table><thead><tr><th width="219">场景</th><th>原因</th><th>解决方案</th></tr></thead><tbody><tr><td><code>401</code> 在新集成中</td><td>密钥缺失、标头拼写错误，或复制粘贴时带有尾随空白/换行。</td><td>从 <a href="https://dashboard.oxylabs.io">控制台</a>重新复制密钥。检查是否存在尾随换行符或 shell 引号处理问题（<code>.strip()</code>).</td></tr><tr><td><code>401</code> 使用有效密钥格式</td><td>密钥属于另一个 Oxylabs 产品。</td><td>确认该密钥是专门在控制台中的 Web API 实例上生成的。</td></tr><tr><td><code>401</code> 在之前可用的密钥上</td><td>密钥已被撤销、替换或删除。</td><td>在你的活动实例上生成新密钥。</td></tr><tr><td><code>401</code> 在所有请求中</td><td>账户订阅或实例已禁用。</td><td>联系 <a href="mailto:support@oxylabs.io">Oxylabs 支持团队</a> 以重新启用账户。</td></tr></tbody></table>

## 手动集成的推荐实践

{% hint style="warning" %}
API 密钥是一种消费凭证。持有它的任何人都可以消耗你的账户配额。
{% endhint %}

<table data-header-hidden><thead><tr><th width="154"></th><th></th></tr></thead><tbody><tr><td><strong>环境变量</strong></td><td>将密钥存储在环境变量（<code>OXYLABS_WEB_API_KEY</code>）或专用密钥管理器中（例如，AWS Secrets Manager、HashiCorp Vault 等）。避免在源代码中硬编码密钥。</td></tr><tr><td><strong>密钥隔离</strong></td><td>为开发、预发布和生产分别使用独立的 Web API 实例，以隔离产品额度消耗并允许独立轮换凭据。</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-api/shen-fen-yan-zheng.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.