API 认证指南

API 认证指南

了解如何使用 API 密钥安全地对 atoship API 进行认证。

概述

认证方式： atoship 的所有 API 请求均采用 API 密钥认证。每个请求都必须在请求头中携带你的 API 密钥。

获取你的 API 密钥

操作步骤：

1. 登录 atoship
2. 进入「设置 → API」
3. 点击「生成 API 密钥」
4. 复制并妥善保存
5. 密钥仅显示一次

API 密钥类型

密钥级别：

认证请求头

必需的请求头：

Authorization: Bearer YOUR_API_KEY

请求示例：

curl -X GET https://api.atoship.com/v1/rates \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

API 密钥格式

密钥结构：

sk_live_xxxxxxxxxxxxxxxxxxxx (Live 密钥)
sk_test_xxxxxxxxxxxxxxxxxxxx (Test 密钥)

代码示例

JavaScript：

const response = await fetch('https://api.atoship.com/v1/rates', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  }
});

Python：

import requests

headers = {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
}
response = requests.get(
    'https://api.atoship.com/v1/rates',
    headers=headers
)

PHP：

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.atoship.com/v1/rates');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk_live_abc123...',
    'Content-Type: application/json'
]);
$response = curl_exec($ch);

安全最佳实践

保护好你的密钥：

1. 切勿在客户端代码中暴露
2. 使用环境变量存储
3. 定期轮换密钥
4. 开发时使用 Test 密钥
5. 监控 API 使用情况

环境变量

安全存储：

# .env 文件（切勿提交到版本库！）
ATOSHIP_API_KEY=sk_live_abc123...

在代码中读取：

const apiKey = process.env.ATOSHIP_API_KEY;

密钥轮换

何时需要轮换：

• 怀疑密钥已泄露
• 员工离职
• 例行安全策略
• 安全审计之后

如何轮换：

1. 生成新密钥
2. 更新各应用配置
3. 使用新密钥测试
4. 吊销旧密钥

速率限制

默认限额：

错误响应

认证错误：

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

常见错误：

多个 API 密钥

适用场景：

• 区分不同环境
• 区分不同服务
• 分配给团队成员
• 提供给外部集成方

密钥权限

范围控制：

• 完全访问（默认）
• 只读
• 指定接口
• 自定义范围

IP 限制

可选安全措施：

• IP 白名单
• 拦截未知来源
• 审计访问日志

使用情况监控

跟踪活动：

• API 调用次数
• 各接口使用情况
• 错误率
• 响应时间

吊销密钥

需要时操作：

1. 进入「设置 → API」
2. 找到对应密钥
3. 点击「吊销」
4. 确认操作

故障排查

认证问题：

1. 核对密钥格式
2. 检查请求头拼写
3. 确认带有 Bearer 前缀
4. 确认密钥处于启用状态
5. 检查是否触发速率限制

测试模式

开发环境搭建：

• 使用 Test API 密钥
• 不产生真实扣费
• 返回模拟响应
• 可放心试验