API 访问

#概述

Yeap Cloud 控制台本身就是通过一组 HTTPS JSON API 工作的。本页说明这组 API 的地址、身份认证方式，以及当前在程序化访问方面的限制。

#API 地址

https://api.yeap.cloud

• 登录相关接口位于 /auth/...，例如 /auth/login、/auth/refresh-token。
• 登录后才能访问的用户接口位于 /api/user/...，例如 /api/user/profile。

请求和响应均为 JSON，请求需带 Content-Type: application/json。

#身份认证

#访问令牌（Access Token）

在控制台登录成功后，服务端会签发一个访问令牌（JWT）。调用 /api/user/... 下的接口时，在请求头中携带：

Authorization: Bearer <访问令牌>

• 访问令牌有效期约 24 小时。
• 令牌缺失、无效或过期时，接口返回 HTTP 401：

{"error": "Unauthorized", "code": 401}

• 账户被停用后，已签发的令牌也会立即失效。
• 在控制台 退出登录 会使当前访问令牌失效，并撤销账户的刷新令牌。

#刷新令牌（Refresh Token）

如果登录时勾选了 记住我，服务端还会同时签发一个刷新令牌，有效期 14 天。访问令牌过期后，可以用刷新令牌换取新的访问令牌，而无需重新登录：

curl -X POST https://api.yeap.cloud/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<刷新令牌>"}'

成功时返回：

{"success": true, "token": "<新的访问令牌>", "user": { ... }}

刷新令牌无效或过期时返回 {"success": false, "error": "Invalid or expired refresh token"}，此时需要重新登录。控制台会自动完成这一刷新过程。

#登录需要人机验证

每次调用 /auth/login 都需要通过人机验证（控制台会弹出验证窗口），开启两步验证的账户还需要输入一次性验证码。因此，目前无法通过脚本完成无人值守的登录。

#示例：读取个人资料

curl https://api.yeap.cloud/api/user/profile \
  -H "Authorization: Bearer <访问令牌>"

成功时返回：

{"success": true, "data": {"id": 123, "username": "...", "email": "...", ...}}

大多数用户接口都返回类似 {"success": true, "data": ...} 的结构；失败时返回 {"success": false, "error": "错误说明"}。

#个人设置中的"API密钥"

个人设置 > API密钥 标签页可以生成、查看和删除 API 密钥：

1. 输入密钥描述，点击 生成密钥。
2. 密钥 只显示一次，请立即复制保存。
3. 在 现有密钥 列表中可以看到密钥 ID、创建时间和最后使用时间，不再需要的密钥请点击 删除。

#CDN "DNS API" 不是 Yeap Cloud 的 API 凭证

CDN管理 > DNS API（/cdn/dns-api）用于保存您在 第三方 DNS 服务商（目前为 Cloudflare）的 API 凭证（推荐使用 API Token，需要 Zone.Zone.Read 和 Zone.DNS.Edit 权限）。这些凭证用于为 CDN 域名以 DNS-01 方式自动申请 SSL 证书，与访问 Yeap Cloud API 无关。详见 CDN 文档。

#其他产品的独立密钥

部分产品有自己的密钥体系，与本页的控制台令牌相互独立，例如 LLM API > 密钥管理。请参阅对应产品的说明。

#安全建议

• 访问令牌和刷新令牌等同于您的登录状态，请勿分享，也不要提交到代码仓库。
• 怀疑令牌泄露时，请在控制台退出登录并 修改密码。
• 为账户开启 两步验证。