Stack Auth 项目中的 API 密钥管理详解

什么是 API 密钥

API 密钥是一种用于身份验证的字符串，它允许用户或应用程序安全地访问 API 服务。在 Stack Auth 项目中，API 密钥为开发者提供了一种简单而有效的方式来控制对后端服务的访问权限。

API 密钥的工作原理

当用户使用 API 密钥发起请求时，系统会经历以下验证流程：

1. 用户/客户端向应用服务器发送带有 API 密钥的请求
2. 应用服务器将 API 密钥转发给 Stack Auth 服务进行验证
3. Stack Auth 服务返回经过身份验证的用户对象
4. 应用服务器处理请求
5. 应用服务器向用户返回响应数据

Stack Auth 中的两种 API 密钥类型

用户 API 密钥

用户 API 密钥与特定用户账户关联，适用于个人开发者或需要直接访问用户资源的场景。

创建用户 API 密钥示例

客户端代码：

const user = await stackApp.getUser();
const apiKey = await user.createApiKey({
  description: "我的客户端应用",
  expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90天后过期
  isPublic: false,
});

服务端代码：

const user = await stackServerApp.getServerUserById("用户ID");
const apiKey = await user.createApiKey({
  description: "管理员创建的API密钥",
  expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30天后过期
  isPublic: false,
});

团队 API 密钥

团队 API 密钥与特定团队关联，适用于需要共享访问权限的协作场景。

创建团队 API 密钥示例

客户端代码：

const user = await stackApp.getUser();
const team = await user.getTeam("团队ID");
const teamApiKey = await team.createApiKey({
  description: "团队集成服务",
  expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60天后过期
  isPublic: false,
});

服务端代码：

const team = await stackServerApp.getTeam("团队ID");
const teamApiKey = await team.createApiKey({
  description: "管理员创建的团队API密钥",
  expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30天后过期
  isPublic: false,
});

API 密钥管理最佳实践

1. 密钥生命周期管理

• 设置合理的过期时间：根据使用场景设置适当的过期时间，避免密钥长期有效
• 定期轮换密钥：建议定期创建新密钥并撤销旧密钥
• 最小权限原则：只为API密钥分配必要的权限

2. 密钥安全存储

• 避免硬编码：不要将API密钥直接写入代码
• 使用环境变量：将密钥存储在环境变量中
• 加密存储：在数据库中加密存储API密钥

3. 密钥使用监控

• 记录使用日志：跟踪API密钥的使用情况
• 设置使用限制：可以限制API密钥的调用频率
• 异常检测：监控异常使用模式

高级功能

列出API密钥

客户端代码：

// 列出用户的所有API密钥
const userApiKeys = await user.listApiKeys();

// 列出团队的API密钥
const team = await user.getTeam("团队ID");
const teamApiKeys = await team.listApiKeys();

服务端代码：

// 列出特定用户的API密钥
const user = await stackServerApp.getServerUserById("用户ID");
const userApiKeys = await user.listApiKeys();

// 列出团队的API密钥
const team = await stackServerApp.getTeam("团队ID");
const teamApiKeys = await team.listApiKeys();

撤销API密钥

当密钥不再需要或可能泄露时，应及时撤销：

客户端代码：

const apiKeys = await user.listApiKeys();
const apiKeyToRevoke = apiKeys.find(key => key.id === "要撤销的密钥ID");

if (apiKeyToRevoke) {
  await apiKeyToRevoke.revoke();
}

检查密钥有效性

const apiKeys = await user.listApiKeys();
const apiKey = apiKeys.find(key => key.id === "要检查的密钥ID");

if (apiKey && apiKey.isValid()) {
  // API密钥有效
} else {
  // API密钥无效（已过期或被撤销）
  const reason = apiKey ? apiKey.whyInvalid() : "未找到";
  console.log(`API密钥无效原因: ${reason}`);
}

总结

Stack Auth 提供了完善的API密钥管理功能，包括创建、列表、撤销和验证等多种操作。通过合理使用用户API密钥和团队API密钥，开发者可以构建安全可靠的应用程序接口。遵循API密钥管理的最佳实践，能够有效提升系统的安全性。