---
title: "认证配置 | Tajo"
description: "为 Brevo API 和 MCP 配置安全认证"
url: https://tajo.io/zh-cn/docs/quick-start/authentication-setup/
markdown: https://tajo.io/zh-cn/docs/quick-start/authentication-setup.md
lang: zh-CN
author: "Set Noa"
author_url: https://tajo.io/zh-cn/set-noa/
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# 认证配置

[Set Noa](https://tajo.io/zh-cn/set-noa/)

Brevo 根据使用场景提供两种认证方式：面向标准 API 访问的 **API 密钥认证**，以及面向 AI 集成的 **MCP Token 认证**。本指南两者都会讲到。

## API 密钥认证

Brevo API 密钥用于以标准 REST API 方式访问全部 Brevo 服务。

### 生成 API 密钥

1. **登录**你的 Brevo 仪表板
2. 进入 **Settings** → **API Keys**
3. 点击 **Generate a New API Key**
4. 给密钥起一个说明性的名字（例如 “My App Production”）
5. **复制并妥善保存**密钥（之后不会再显示）

### API 密钥安全最佳实践

#### ✅ 应该做

- 用环境变量**安全保存密钥**
- 开发环境和生产环境**使用不同的密钥**
- **定期轮换密钥**（建议每 90 天一次）
- **把密钥权限限制**在实际需要的范围内
- 在仪表板中**监控密钥用量**

#### ❌ 不要做

- **绝不要把密钥提交**到版本控制
- **不要把密钥硬编码**在应用里
- **不要通过**邮件或聊天工具**分享密钥**
- **不要用生产密钥**做测试

### 环境变量

把 API 密钥保存为环境变量：

#### Linux/macOS（.bashrc 或 .zshrc）

```bash
export BREVO_API_KEY="your_api_key_here"
```

#### Windows（命令提示符）

```cmd
set BREVO_API_KEY=your_api_key_here
```

#### Node.js（.env 文件）

```env
BREVO_API_KEY=your_api_key_here
```

```javascript
// Load from environment
const apiKey = process.env.BREVO_API_KEY;
```

#### Python

```python
import os

api_key = os.getenv('BREVO_API_KEY')
```

#### PHP

```php
$apiKey = $_ENV['BREVO_API_KEY'];
// or
$apiKey = getenv('BREVO_API_KEY');
```

### 认证请求头

把 API 密钥放进请求头：

#### 标准请求头格式

```http
GET /v3/account HTTP/1.1
Host: api.brevo.com
Accept: application/json
api-key: your_api_key_here
```

#### JavaScript 示例

```javascript
const headers = {
  'Accept': 'application/json',
  'api-key': process.env.BREVO_API_KEY
};

fetch('https://api.brevo.com/v3/account', { headers })
  .then(response => response.json())
  .then(data => console.log(data));
```

#### Python Requests

```python
import requests

headers = {
    'Accept': 'application/json',
    'api-key': os.getenv('BREVO_API_KEY')
}

response = requests.get('https://api.brevo.com/v3/account', headers=headers)
```

### 密钥权限与范围

不同的 API 密钥可以拥有不同的权限：

- **只读**：只允许 GET 请求
- **发送邮件**：事务邮件权限
- **管理联系人**：创建、更新、删除联系人
- **营销活动管理**：创建并发送营销活动
- **完全访问**：全部 API 端点

### 测试认证是否可用

用这个端点验证认证是否生效：

```bash
curl -X GET "https://api.brevo.com/v3/account" \
  -H "Accept: application/json" \
  -H "api-key: $BREVO_API_KEY"
```

**成功响应（200 OK）：**

```json
{
  "email": "your-email@company.com",
  "firstName": "John",
  "lastName": "Doe"
}
```

**认证错误（401 Unauthorized）：**

```json
{
  "code": "unauthorized",
  "message": "Invalid API key provided"
}
```

### 密钥轮换

轮换 API 密钥的步骤：

1. 在仪表板中**生成新密钥**
2. 用新密钥**更新环境变量**
3. 用新密钥**部署应用**
4. **充分测试**，确认一切正常
5. 确认新密钥无误后**吊销旧密钥**

### 监控 API 密钥用量

在 Brevo 仪表板中跟踪 API 密钥用量：

- **每日/每月请求数**
- **按端点划分的错误率**
- **地域使用分布**
- **用量高峰时段**

### 多 API 密钥策略

对于较大的应用，可以考虑使用多个 API 密钥：

- **生产**：真实客户数据和邮件
- **预发布**：上线前测试
- **开发**：本地开发与测试
- **监控**：健康检查和指标
- **第三方**：外部集成

---

## MCP Token 认证

**Brevo Model Context Protocol（MCP）** 是一个 AI 集成框架，让 AI 助手能够与 Brevo 服务交互。MCP 使用独立的认证方式，通过 MCP token 完成。

### 什么是 MCP？

MCP 为 AI 访问 Brevo API 提供标准化通道：

- **传输方式**：HTTPS
- **基础 URL**：`https://mcp.brevo.com/v1/`
- **响应格式**：JSON
- **认证方式**：MCP Token（与 API 密钥不同）

### 生成 MCP Token

1. **登录**你的 Brevo 仪表板
2. 进入 **Settings** → **MCP Tokens**（或账号设置）
3. 生成新的 MCP token
4. **复制并妥善保存**该 token

> **注意**：MCP 目前仅对抢先体验用户开放。

### 使用 MCP Token

MCP token 专门用于 AI 集成和 Model Context Protocol 连接：

```bash
export BREVO_MCP_TOKEN="your_mcp_token_here"
```

向 MCP 端点发请求时带上 MCP token：

```http
GET /v1/account HTTP/1.1
Host: mcp.brevo.com
Accept: application/json
Authorization: Bearer your_mcp_token_here
```

### MCP 与 API 密钥对比

| 特性 | API 密钥 | MCP Token |
| --- | --- | --- |
| **使用场景** | 标准 REST API 访问 | AI 集成与 MCP 连接 |
| **基础 URL** | api.brevo.com | mcp.brevo.com |
| **请求头** | `api-key` | `Authorization: Bearer` |
| **可用范围** | 所有用户 | 抢先体验用户 |

### MCP 安全最佳实践

- 把 MCP token 与 API 密钥分开保存
- 用环境变量存放 token
- 定期轮换 token
- 绝不要把 token 提交到版本控制
- 在仪表板中监控 MCP 用量

---

## 认证问题排查

### 常见 API 密钥问题

**API 密钥格式无效**

- 密钥长度应正好是 64 个字符
- 检查是否多出空格或其他字符

**权限错误**

- 确认密钥拥有所需权限
- 在仪表板中检查密钥是否处于启用状态

**速率限制**

- 认证失败也会计入速率限制
- 用正确的凭证重试前先等待一段时间

**地域限制**

- 部分账号设置了 IP 限制
- 如需把 IP 加入白名单，请联系支持团队

### 常见 MCP Token 问题

**MCP 不可用**

- 确认你已获得 MCP 功能的抢先体验资格
- 联系 Brevo 支持团队申请开通

**Token 无效**

- 确认 token 复制完整且不含空格
- 检查 token 是否已过期或被吊销

**基础 URL 错误**

- MCP token 只能用于 mcp.brevo.com
- 不要把 MCP token 用在 api.brevo.com 的端点上

## 后续步骤

- [了解速率限制](https://tajo.io/zh-cn/docs/rate-limits/)
- [安装 SDK](https://tajo.io/zh-cn/docs/sdks-libraries/)
- [发起第一个 API 调用](https://tajo.io/zh-cn/docs/quick-start/first-api-call/)