---
title: "身份验证"
description: "了解如何使用 API key 对 API 请求进行身份验证,以及如何安全地管理你的凭证。"
---

# 身份验证

Minds 研究 API 需要 API 密钥或经批准的 OAuth 授权。公共页面和发现文档无需登录即可阅读。

## 获取你的 API Key

1. 登录到你的 Minds 账户
2. 进入 **Settings** → **API Keys**
3. 点击 **Generate New API Key**
4. 立即复制你的 API key(你将无法再次查看它!)

API key 以 `minds_` 为前缀,形如:`minds_0000111122223333444455556666777788889999aaaabbbb`

## 使用你的 API Key

在每次请求的 `Authorization` header 中包含你的 API key:

```bash
Authorization: Bearer minds_your_api_key_here
```

### 请求示例

```bash
curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key"
```

## 安全最佳实践

### 妥善保管你的 Key

- **切勿**将 API key 提交到版本控制系统
- **切勿**在公开论坛或聊天中分享 key
- 将 key 存储在环境变量或安全的密钥保管库中
- 定期轮换 key 以保证安全

### 使用环境变量

```bash
# 将你的 key 设置为环境变量
export MINDS_API_KEY="minds_your_api_key_here"

# 在请求中使用它
curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer $MINDS_API_KEY"
```

### 定期轮换 Key

如果你怀疑某个 key 已泄露:

1. 生成新的 API key
2. 更新你的应用程序以使用新 key
3. 删除旧 key

## 管理 API Key

### 列出你的 API Key

```bash
GET /api/v1/api-keys
```

返回你的 API key 列表及元数据(实际的 key 值永远不会被返回):

```json
[
  {
    "id": "key-id",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "lastUsedAt": "2025-12-10T13:00:00.000Z"
  }
]
```

### 创建新的 API Key

```bash
POST /api/v1/api-keys
```

响应中包含实际的 key 值(这是你唯一能看到它的机会):

```json
{
  "id": "new-key-id",
  "key": "minds_0000111122223333444455556666777788889999aaaabbbb",
  "createdAt": "2025-12-10T12:00:00.000Z"
}
```

⚠️ **重要:** 立即保存 `key` 值!你将无法再次获取它。

### 删除 API Key

```bash
DELETE /api/v1/api-keys/{keyId}
```

成功时返回 `204 No Content`,响应体为空。

## 身份验证错误

### 401 Unauthorized

你的 API key 缺失或无效。

```json
{
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

**解决方案:**

- 检查是否已包含 `Authorization` header
- 验证你的 API key 是否正确
- 确保使用了 `Bearer` 前缀
- 如果旧 key 已被删除,请生成新的 key

## 按计划分级的访问权限

API 访问是付费计划支持的功能，并受产品中显示或合同约定的资源、响应和工作区限额约束。不要在集成中写死限额；请处理结构化的 `PLAN_LIMIT` 和 `plan_limited` 响应。Starter 计划在 API payload 中表示为 `"premium"`。

[查看计划](/pricing)

## 代理只读连接

代理可通过 [auth.md](/auth.md) 请求只读访问。请登录指定的已验证账户，输入代理显示的六位数代码，并批准页面列出的权限。请求在十分钟后过期。

初始注册凭据只能查询自身状态。批准后，代理会获得权限受限的 OAuth 令牌，用于读取支持的 Mind、受众和研究数据。代理不能修改研究、启动付费任务、创建 API 密钥或管理账户。可在设置中移除 OAuth 连接来撤销访问权限。

MCP 使用[受保护资源元数据](/.well-known/oauth-protected-resource/mcp)。公共页面无需读取权限。