认证

AstroAPI 根据您的使用场景支持多种认证方式。

API 密钥认证

API 密钥是服务器间通信的推荐方式。

获取 API 密钥

登录 AstroAPI 控制台
进入 Settings > API Keys
点击 Create API Key
配置权限和速率限制
复制生成的密钥（该密钥仅显示一次）

使用 API 密钥

在 X-Api-Key 请求头中包含您的 API 密钥：

bash

curl -X GET "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: ak_live_xxxxxxxxxxxx"

API 密钥权限

API 密钥可以限定为特定权限范围：

权限	描述
`calc:read`	访问计算端点
`content:read`	访问内容/解读端点
`chart:read`	访问星盘渲染端点
`modules:read`	访问已购买的模块

角色

AstroAPI 在组织内使用基于角色的访问控制：

角色	描述
`owner`	完全访问所有组织功能
`manager`	可以管理用户、账单和内容
`member`	基本的计算和内容读取访问权限

角色权限

权限	owner	manager	member	描述
`org:create`	✅			创建组织
`org:read`	✅	✅	✅	读取组织信息
`org:update`	✅	✅		更新组织信息
`org:users:read`	✅	✅		读取用户信息
`org:users:create`	✅	✅		邀请用户
`org:users:update`	✅	✅		更新用户信息
`org:users:delete`	✅	✅		移除用户
`billing:read`	✅	✅		查看账单
`billing:manage`	✅	✅		管理账单
`content:read`	✅	✅	✅	读取内容
`content:create`	✅	✅		创建内容
`content:update`	✅	✅		更新内容
`content:delete`	✅	✅		删除内容
`content:custom-copy`	✅	✅	✅	创建自定义副本
`content:restore`	✅	✅		恢复内容
`calc:use`	✅	✅	✅	使用计算端点
`chart:use`	✅	✅	✅	使用星盘端点
`modules:read`	✅	✅	✅	读取模块信息
`admin:access`	✅			管理员访问

组织上下文

对于多租户应用程序，API 密钥的作用范围限定于组织。组织上下文根据所使用的 API 密钥自动应用。

域名限制

API 密钥可以配置域名限制，以限制哪些网站可以使用它们：

example.com — 精确域名匹配
*.example.com — 所有子域名
* — 允许所有域名（不推荐）

在控制台中创建或编辑 API 密钥时配置域名限制。

重要限制

域名限制仅能防止基于浏览器的滥用。它们依赖于 Origin 和 Referer 请求头，浏览器会强制执行这些头，但在浏览器之外（如 curl、脚本、服务端代码）可以轻易被伪造。

客户端与服务端使用

服务器间通信（推荐）

对于生产应用程序，请始终在后端服务器上使用 API 密钥：

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│   Browser   │ ───► │  Your Backend   │ ───► │  AstroAPI   │
│  (no keys)  │      │  (API key here) │      │             │
└─────────────┘      └─────────────────┘      └─────────────┘

这种方式：

保持您的 API 密钥安全和隐藏
允许您添加自己的认证层
防止最终用户提取 API 密钥
支持请求签名和额外的安全措施

客户端 / 浏览器使用

如果您必须在浏览器中直接使用 API 密钥（例如，静态站点上的嵌入式小组件），请注意以下限制：

API 密钥是可见的，存在于 JavaScript 源代码和网络请求中
任何人都可以提取您网站上的密钥
域名限制仅能防止其他网站通过 JavaScript 使用您的密钥——无法防止有人复制密钥并在其他地方使用

对于客户端使用，我们建议：

启用域名限制
设置严格的速率限制
使用较短的过期时间
监控异常使用情况

客户责任

重要

您负责 API 密钥的安全性和使用情况。

使用您的 API 密钥发出的所有 API 请求都计入您的配额并从您的账户计费，无论请求是由您还是由获得您密钥的他人发出的。

如果您在客户端代码中暴露了 API 密钥并被滥用，您将对由此产生的使用量和费用负责。AstroAPI 无法区分使用有效 API 密钥发出的合法请求和未授权请求。

为降低风险：

尽可能使用服务器间通信
切勿将 API 密钥提交到版本控制
如果怀疑密钥已泄露，立即轮换密钥
设置使用量警报以检测意外峰值

安全最佳实践

在生产应用程序中使用服务器间通信
除非绝对必要，否则切勿在客户端代码中暴露 API 密钥
定期轮换 API 密钥
使用所需的最小权限
为客户端密钥启用域名限制
设置适当的速率限制
在控制台中监控 API 密钥使用情况

认证 ​

API 密钥认证 ​

获取 API 密钥 ​

使用 API 密钥 ​

API 密钥权限 ​

角色 ​

角色权限 ​

组织上下文 ​

域名限制 ​

客户端与服务端使用 ​

服务器间通信（推荐） ​

客户端 / 浏览器使用 ​

客户责任 ​

安全最佳实践 ​

认证