智能体应优先使用 OAuth:无需复制密钥,且用户可以直接登出而不必轮换密钥。仅在无人值守的代码环境中使用 API key。
OAuth:用于 MCP 和 CLI
你无需提前创建任何内容。- MCP。 将
https://mcp.aisa.one/mcp添加到你的客户端。首次使用时,服务器会返回401并附带 OAuth 元数据(RFC 9728),客户端打开浏览器,你点击 Allow 即可。客户端会保存 token;智能体不得读取或复用该 token。各客户端的具体步骤参见:通过 MCP 连接。 - CLI。
aisa login执行相同的浏览器流程,并将自动刷新的会话存储在~/.aisa/tokens.json中。使用aisa balance检查。参见使用 CLI。
Authorization: Bearer $AISA_API_KEY)。对于 CLI,设置 AISA_API_KEY 环境变量会覆盖已存储的会话。
部分账户级视图需要 OAuth。例如,GET /v1/usage 使用 scope=account 时需要 OAuth 会话;API key 只能读取自身的用量。
API key
在每个请求中以 Bearer token 形式发送密钥:首次充值前,账户使用注册赠送额度,只能调用
GET /v1/models 中标记为 "recharge_required": false 的模型。其他模型会返回 402,error.code = "recharge_required",充值后即可调用。https://api.aisa.one/v1)、数据 API(https://api.aisa.one/apis/v1)和 MCP。Anthropic 兼容的 /v1/messages 路由也接受将其作为 x-api-key 传递,这正是 Anthropic SDK 的默认行为。参见 OpenAI / Anthropic SDK。
密钥设置
在 API Keys 中创建或编辑密钥时,可以设置:- Name — 按应用或环境为密钥命名,例如
prod-web或ci。 - Spending limit — 该密钥最多可消费的金额(美元),或设为 Unlimited。密钥的实际可用额度取决于其剩余限额和账户余额中较低的那个。当限额耗尽时,密钥状态变为 exhausted,请求返回
402 insufficient_api_key_balance。 - Allowed IPs — 将密钥限制为特定 IP 地址或 CIDR 范围。
- Status — 临时禁用密钥而不删除它。
轮换与吊销
轮换步骤:创建新密钥,部署到所有环境,在 Usage & Logs 中确认旧密钥已无流量,然后吊销旧密钥。定期轮换,并在任何有权限的人员离开后立即轮换。 如果密钥泄露,先吊销再调查。使用已禁用、已过期或无效密钥的请求将返回401(api_key_disabled、expired_api_key、invalid_api_key)。参见错误。
密钥存储
本地开发
本地开发
将密钥保存在
.env 文件中,通过 python-dotenv 或 dotenv 加载,并将 .env 添加到 .gitignore。CI/CD
CI/CD
将密钥作为 CI secret 存储,并以环境变量形式暴露。为 CI 使用专用密钥并设置较低的消费限额。
服务器与云平台
服务器与云平台
使用你的平台的密钥管理服务(AWS Secrets Manager、GCP Secret Manager、Azure Key Vault,或 Fly、Render、Railway 的加密环境变量)。轮换密钥后重启服务即可生效。
客户端应用
客户端应用
切勿将密钥放在用户可以查看的代码中。通过你控制的后端调用 AIsa,该后端负责认证用户、施加用户级限额,并使用服务端密钥转发请求。
相关
计费与额度
消费如何计量、报价和设定上限。
安全与隐私
数据处理、保留策略与传输安全。