API身份验证与Bearer令牌

身份验证的工作原理

1. 注册并登录您的 Quote3D 账户。
2. 从您的仪表板的“Tokens”选项卡下生成一个 API token。
3. 在您的 API 请求中包含 token。支持 Authorization: Bearer，也接受 X-API-Token:
   Authorization: Bearer YOUR_TOKEN_HERE
4. 服务器会验证您的令牌，如果令牌有效且未过期，则授予访问权限。

令牌作用域

令牌的作用域决定它能访问哪些端点。作用域在创建令牌时选定，可在控制台的「令牌」页面查看。

• 完全访问——服务器端令牌的默认选项，可访问您套餐允许的所有端点。
• 小组件——用于嵌入店铺的令牌。它仅限于可嵌入小组件所需的范围，无法访问Webhook、账户信息、分析、用量或额度。

调用令牌作用域之外的端点，即使令牌本身有效也会被拒绝并返回403。如果同一个令牌在别处可用而某个请求返回403，请首先检查它的作用域。

令牌生命周期

• 令牌值只在创建时显示一次，之后无法找回——请立即保存到您的密钥管理器中。若不慎丢失，请轮换令牌以获取新值。
• 创建令牌时可以设置有效期。过期的令牌将停止工作并返回401；控制台会显示每个令牌的到期日期。
• 轮换令牌会签发新值并立即作废旧值。请在轮换前部署新值，因为使用旧令牌的进行中请求会立刻开始失败。
• 令牌可以限制在一组IP地址内。来自其他地址的调用会被拒绝并返回403——这是迁移服务器或更换NAT网关后常见的意外。
• 您的套餐限制可持有的令牌数量。免费套餐允许一个服务器令牌和一个小组件令牌。

身份验证失败时

被拒绝的请求会返回标准错误信封，包含 success: false 和一条简短消息。请根据HTTP状态码分支，而不要依赖可能被改写的消息文本。

{
  "success": false,
  "error": "API token has expired"
}

• 401 —— 令牌缺失、格式错误、已过期或已吊销。请检查标头名称，并确认复制时值没有被截断。
• 403 —— 令牌有效但不允许执行此调用。常见原因是作用域限制，或IP白名单中不包含调用方。

令牌格式

Quote3D 令牌是 bearer-style API 凭证。客户端应将其视为不透明的密钥，并避免依赖于令牌的内部结构。

JWT 由三个部分组成：

1. Header（头部）：指定签名算法和令牌类型。
2. Payload（有效载荷）：包含用户数据和声明（如用户 ID、电子邮件和过期时间）。
3. Signature（签名）：验证令牌是否被篡改。

JWT 的样子如下：

对于集成，重要的规则很简单：安全地存储令牌，在每个请求中发送它，并避免在客户端代码中解析或暴露它，除非集成明确需要客户端令牌。

示例：使用您的令牌

以下是如何使用 curl 调用您的令牌。请始终使用一种身份验证标头样式。

或者在 API Playground 中，将您的令牌粘贴到授权模态框（锁图标）中以验证您的会话。您还可以在自定义集成中使用 X-API-Token 标头（如果该标头更适合）。