# 认证

> 在 OAuth 2.1 和 API 密钥之间做出选择，安全地发送 Bearer 凭据，并从认证失败中恢复。

Canonical URL: https://s1.dev/zh/docs/essentials/authentication

Search1API 接受 OAuth 访问令牌和用户自行管理的 API 密钥作为 Bearer 凭据。调用 `https://api.search1api.com` 上需要认证的端点时，两者都通过同一个请求头发送：

```http
Authorization: Bearer YOUR_ACCESS_TOKEN_OR_API_KEY
```

## 选择认证方式

**使用 OAuth 2.1**：适用于 AI 智能体、原生 CLI 或支持 OAuth 的 MCP 客户端需要由用户批准访问的场景。客户端可以发现授权服务器，以公共客户端身份注册，使用 Authorization Code + PKCE，并在不要求用户复制长期 API 密钥的情况下刷新访问权限。

**使用 API 密钥**：适用于固定的服务端到服务端集成、CI、已有的 SDK 配置，或尚不支持 OAuth 发现的客户端。API 密钥仍然完全受支持。

两种方式使用的是同一个 Search1API 账户、积分余额、计费规则和速率限制。

## OAuth 2.1

从客户端所使用的受保护资源开始：

- REST API：[`https://api.search1api.com/.well-known/oauth-protected-resource`](https://api.search1api.com/.well-known/oauth-protected-resource)
- Hosted MCP：[`https://mcp.search1api.com/.well-known/oauth-protected-resource`](https://mcp.search1api.com/.well-known/oauth-protected-resource)

这些文档会公布 Search1API 的授权服务器。当 Bearer 凭据无效时，返回的 `401` 响应也会包含 `WWW-Authenticate` 质询，其中带有对应的 `resource_metadata` URL。在没有提供凭据时，Hosted MCP 端点也会发送同样的发现质询。

Search1API 支持动态客户端注册（Dynamic Client Registration）、带 PKCE（`S256`）的 Authorization Code 流程、访问令牌和刷新令牌，以及令牌吊销。账户所有者本人仍需登录并批准该客户端；动态注册不会在后台悄悄创建 Search1API 用户。

完整的协议流程和端点列表，请阅读对智能体友好的 [`auth.md`](https://s1.dev/auth.md)。

### 官方 CLI

Search1API CLI 实现了完整的公共客户端流程：

```bash
s1 login
s1 config show
```

它会进行动态注册，打开浏览器等待批准，将得到的 OAuth 凭据保存在本地，并自动刷新过期的访问令牌。安装方式和备选方案请参阅 [CLI](https://s1.dev/zh/docs/integrations/cli)。

### Hosted MCP

支持 OAuth 的 MCP 客户端可以直接指向 `https://mcp.search1api.com/mcp`，并按照服务器返回的受保护资源质询完成认证。不支持 OAuth 的客户端可以继续使用 API 密钥。两种配置方式请参阅 [MCP 服务器](https://s1.dev/zh/docs/integrations/mcp)。

## API 密钥

### 获取密钥

登录 [app.s1.dev](https://app.s1.dev)，打开 **API Keys** 页面并创建密钥。在仪表盘中，你可以为已有密钥添加标签、显示、复制和删除。

### 将密钥保存在服务端

像对待密码一样对待密钥。把它存放在环境变量或密钥管理服务中，切勿在浏览器代码、移动应用安装包、日志或公开代码仓库中暴露。

> **warn:** 任何持有该密钥的人都可以消耗你账户的余额发起请求。如果密钥泄露，请立即替换并删除旧密钥。

### 按工作负载区分密钥

为不同环境或服务使用不同的密钥，这样你可以区分流量来源，并在吊销某个集成时不影响其他集成。在仪表盘中为密钥添加清晰的标签，例如 `production-api`、`staging` 或 `claude-mcp`。

同一账户下的所有密钥共用同一个积分余额。区分密钥有助于归因和吊销，但不会产生独立的余额。

### 轮换或吊销密钥

目前没有原地轮换的操作。要替换密钥：

1. 创建新密钥。
2. 更新应用或集成配置。
3. 确认使用新密钥的请求能够成功。
4. 删除旧密钥。

删除密钥即吊销该密钥。继续使用它的请求会返回 `401 Unauthorized`。

## 认证失败

无效、过期或已吊销的 Bearer 凭据会返回 `401`。支持 OAuth 的客户端应利用随附的 `WWW-Authenticate` 元数据发现授权服务，或在重试前刷新过期的令牌。

由于 Search1API 同时支持按请求付费的支付协议，目前在付费 API 端点上，未携带 Bearer 凭据的请求会收到 `402` 支付质询。而 Hosted MCP 端点在没有凭据时返回的是 `401` OAuth 发现质询。

响应体格式和恢复建议请参阅[错误处理](https://s1.dev/zh/docs/essentials/error-handling)。