Thiết lập xác thực

Brevo cung cấp hai phương thức xác thực tùy theo nhu cầu sử dụng: xác thực bằng khóa API cho truy cập API tiêu chuẩn và xác thực bằng token MCP cho các tích hợp AI. Hướng dẫn này trình bày cả hai phương thức.

Xác thực bằng khóa API

Khóa API của Brevo được dùng để truy cập REST API tiêu chuẩn tới mọi dịch vụ của Brevo.

Tạo khóa API của bạn

1. Đăng nhập vào bảng điều khiển Brevo
2. Vào Settings → API Keys
3. Nhấp Generate a New API Key
4. Đặt cho khóa một cái tên dễ nhận biết (ví dụ “My App Production”)
5. Sao chép và lưu khóa ở nơi an toàn (bạn sẽ không thấy lại khóa này nữa!)

Thực hành tốt về bảo mật khóa API

✅ NÊN LÀM

• Lưu khóa an toàn bằng biến môi trường
• Dùng khóa khác nhau cho môi trường phát triển và môi trường sản xuất
• Xoay vòng khóa định kỳ (khuyến nghị mỗi 90 ngày)
• Giới hạn quyền của khóa ở đúng mức cần thiết
• Theo dõi mức sử dụng khóa trong bảng điều khiển

❌ KHÔNG NÊN

• Đừng bao giờ commit khóa vào hệ thống quản lý phiên bản
• Đừng gán cứng khóa trong ứng dụng của bạn
• Đừng chia sẻ khóa qua email hay chat
• Đừng dùng khóa của môi trường sản xuất để kiểm thử

Biến môi trường

Lưu khóa API của bạn dưới dạng biến môi trường:

Linux/macOS (.bashrc hoặc .zshrc)

export BREVO_API_KEY="your_api_key_here"

Windows (Command Prompt)

set BREVO_API_KEY=your_api_key_here

Node.js (file .env)

BREVO_API_KEY=your_api_key_here

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

Python

import os

api_key = os.getenv('BREVO_API_KEY')

PHP

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

Header xác thực

Đưa khóa API vào header của request:

Định dạng header tiêu chuẩn

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

Ví dụ 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

import requests

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

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

Quyền và phạm vi của khóa

Các khóa API khác nhau có thể có quyền khác nhau:

• Chỉ đọc: Chỉ cho phép request GET
• Gửi email: Quyền gửi email giao dịch
• Quản lý liên hệ: Tạo, cập nhật, xóa liên hệ
• Quản lý chiến dịch: Tạo và gửi chiến dịch
• Toàn quyền: Mọi endpoint API

Kiểm tra xác thực của bạn

Dùng endpoint sau để xác nhận việc xác thực hoạt động:

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

Phản hồi thành công (200 OK):

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe"
}

Lỗi xác thực (401 Unauthorized):

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

Xoay vòng khóa

Để xoay vòng khóa API của bạn:

1. Tạo khóa mới trong bảng điều khiển
2. Cập nhật biến môi trường với khóa mới
3. Triển khai ứng dụng với khóa mới
4. Kiểm thử kỹ lưỡng để bảo đảm mọi thứ vẫn chạy
5. Thu hồi khóa cũ khi đã yên tâm với khóa mới

Theo dõi mức sử dụng khóa API

Theo dõi mức sử dụng khóa API trong bảng điều khiển Brevo:

• Số request mỗi ngày và mỗi tháng
• Tỷ lệ lỗi theo từng endpoint
• Phân bố sử dụng theo khu vực địa lý
• Khung giờ cao điểm

Chiến lược dùng nhiều khóa API

Với các ứng dụng lớn hơn, hãy cân nhắc dùng nhiều khóa API:

• Sản xuất: Dữ liệu và email của khách hàng thật
• Staging: Kiểm thử trước khi lên sản xuất
• Phát triển: Phát triển và kiểm thử cục bộ
• Giám sát: Kiểm tra tình trạng hệ thống và thu thập số liệu
• Bên thứ ba: Các tích hợp bên ngoài

Xác thực bằng token MCP

Brevo Model Context Protocol (MCP) là một khung tích hợp AI cho phép trợ lý AI tương tác với các dịch vụ của Brevo. MCP dùng một phương thức xác thực riêng thông qua token MCP.

MCP là gì?

MCP cung cấp cho AI quyền truy cập chuẩn hóa vào các API của Brevo thông qua:

• Giao vận: HTTPS
• URL gốc: https://mcp.brevo.com/v1/
• Định dạng phản hồi: JSON
• Xác thực: Token MCP (khác với khóa API)

Tạo token MCP của bạn

1. Đăng nhập vào bảng điều khiển Brevo
2. Vào Settings → MCP Tokens (hoặc phần cài đặt tài khoản)
3. Tạo một token MCP mới
4. Sao chép và lưu token ở nơi an toàn

Lưu ý: Hiện MCP chỉ khả dụng với người dùng thuộc chương trình truy cập sớm.

Sử dụng token MCP

Token MCP được dùng riêng cho các tích hợp AI và kết nối Model Context Protocol:

export BREVO_MCP_TOKEN="your_mcp_token_here"

Đưa token MCP vào request gửi tới các endpoint MCP:

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

So sánh MCP và khóa API

Thực hành tốt về bảo mật MCP

• Lưu token MCP tách riêng khỏi khóa API
• Dùng biến môi trường để lưu token
• Xoay vòng token định kỳ
• Đừng bao giờ commit token vào hệ thống quản lý phiên bản
• Theo dõi mức sử dụng MCP trong bảng điều khiển

Khắc phục sự cố xác thực

Các vấn đề thường gặp với khóa API

Khóa API sai định dạng

• Khóa phải dài đúng 64 ký tự
• Kiểm tra xem có khoảng trắng hoặc ký tự thừa không

Lỗi quyền truy cập

• Kiểm tra khóa của bạn có đủ quyền cần thiết
• Kiểm tra khóa còn đang hoạt động trong bảng điều khiển

Giới hạn tần suất

• Các lần xác thực thất bại vẫn bị tính vào giới hạn tần suất
• Hãy chờ một lúc trước khi thử lại bằng thông tin xác thực đúng

Hạn chế theo khu vực địa lý

• Một số tài khoản có giới hạn theo địa chỉ IP
• Hãy liên hệ bộ phận hỗ trợ nếu bạn cần thêm IP vào danh sách cho phép

Các vấn đề thường gặp với token MCP

MCP không khả dụng

• Hãy chắc chắn bạn có quyền truy cập sớm vào các tính năng MCP
• Liên hệ bộ phận hỗ trợ của Brevo để xin quyền truy cập

Token không hợp lệ

• Kiểm tra token được sao chép chính xác, không dính khoảng trắng
• Kiểm tra token chưa hết hạn hoặc bị thu hồi

Sai URL gốc

• Token MCP chỉ hoạt động với mcp.brevo.com
• Đừng dùng token MCP với các endpoint của api.brevo.com

Bước tiếp theo

• Tìm hiểu về giới hạn tần suất
• Cài đặt SDK
• Thực hiện lệnh gọi API đầu tiên