KillB API 使用 JWT（JSON Web Tokens） 进行身份验证。所有 API 请求必须在 Authorization 标头中包含有效的访问令牌。
API 身份验证使用 电子邮件/密码 登录和 API 密钥 的组合，用于不同的访问模式。
身份验证方法
用于大多数 API 操作。通过登录端点获取。最适合： Web 和移动应用程序、用户特定操作
用于服务器到服务器的操作和 webhooks。最适合： 后端服务、管理操作
获取您的凭证
- 在 https://otc.killb.com/auth/jwt/register 注册 KillB 账户
- 在 otc.killb.com 访问门户
- 获取凭证：
- 您的登录电子邮件和密码
- 从门户设置中获取您的 API 密钥
登录流程
步骤 1：生成访问令牌
请求：
响应：
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600000,
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
curl --request POST \
--url https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/login \
--header 'Content-Type: application/json' \
--data '{
"email": "[email protected]",
"password": "your-password"
}'
步骤 2：使用访问令牌
在所有 API 请求的 Authorization 标头中包含访问令牌：
Authorization: Bearer YOUR_ACCESS_TOKEN
curl --request GET \
--url https://teste-94u93qnn.uc.gateway.dev/api/v2/users \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
刷新令牌
访问令牌在 1 小时后过期。使用刷新令牌获取新的访问令牌：
POST /api/v2/auth/refresh
{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600000
}
async function refreshAccessToken(refreshToken) {
const response = await fetch('https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/refresh', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ refreshToken })
});
const data = await response.json();
return data.accessToken;
}
在您的应用程序中实现自动令牌刷新，以保持不间断的 API 访问。
安全最佳实践
- 永远不要将凭证提交到版本控制
- 使用环境变量存储 API 密钥和令牌
- 定期轮换 API 密钥
- 使用密钥管理服务（AWS Secrets Manager、HashiCorp Vault 等）
- 安全存储令牌（加密存储、安全 cookie）
- 实现自动令牌刷新
- 注销时清除令牌
- 设置适当的令牌过期时间
- 始终对 API 请求使用 HTTPS
- 为移动应用实现证书固定
- 验证 SSL 证书
- 使用安全网络连接
- 不要向最终用户暴露身份验证错误
- 记录身份验证失败以进行监控
- 对登录尝试实施速率限制
- 优雅地处理令牌过期
身份验证错误
常见的身份验证错误响应：
| 状态代码 | 错误 | 描述 |
|---|
401 | 未授权 | 无效或过期的令牌 |
403 | 禁止 | 有效令牌但权限不足 |
400 | 错误请求 | 无效的凭证格式 |
{
"errorCode": "AUTH.0001",
"message": ["Invalid credentials"],
"statusCode": "401"
}
测试身份验证
使用沙盒环境测试身份验证：
沙盒 URL： https://teste-94u93qnn.uc.gateway.dev
为沙盒测试创建单独的测试账户。沙盒凭证在生产环境中不起作用。
示例：完整的身份验证流程
这是一个管理身份验证状态的完整示例：
class KillBAuth {
constructor(email, password) {
this.email = email;
this.password = password;
this.accessToken = null;
this.refreshToken = null;
this.baseUrl = 'https://teste-94u93qnn.uc.gateway.dev';
}
async login() {
const response = await fetch(`${this.baseUrl}/api/v2/auth/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: this.email,
password: this.password
})
});
const data = await response.json();
this.accessToken = data.accessToken;
this.refreshToken = data.refreshToken;
return data;
}
async refresh() {
const response = await fetch(`${this.baseUrl}/api/v2/auth/refresh`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
refreshToken: this.refreshToken
})
});
const data = await response.json();
this.accessToken = data.accessToken;
this.refreshToken = data.refreshToken;
return data;
}
getAuthHeaders() {
return {
'Authorization': `Bearer ${this.accessToken}`,
'Content-Type': 'application/json'
};
}
}
// Usage
const auth = new KillBAuth('[email protected]', 'your-password');
await auth.login();
// Make authenticated request
const response = await fetch(`${auth.baseUrl}/api/v2/users`, {
headers: auth.getAuthHeaders()
});
下一步
