跳转到主要内容
AIsa 接受两种凭据,两者共用同一个账户余额。 智能体应优先使用 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。
当 OAuth 不可用时(例如在 CI 中),MCP 客户端也可以发送 API key(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)。参见错误。

密钥存储

你的 API key 可直接消费账户余额。切勿将其提交到 git 仓库、在聊天中分享或包含在客户端代码中。
将密钥保存在 .env 文件中,通过 python-dotenv 或 dotenv 加载,并将 .env 添加到 .gitignore。
将密钥作为 CI secret 存储,并以环境变量形式暴露。为 CI 使用专用密钥并设置较低的消费限额。
使用你的平台的密钥管理服务(AWS Secrets Manager、GCP Secret Manager、Azure Key Vault,或 Fly、Render、Railway 的加密环境变量)。轮换密钥后重启服务即可生效。
切勿将密钥放在用户可以查看的代码中。通过你控制的后端调用 AIsa,该后端负责认证用户、施加用户级限额,并使用服务端密钥转发请求。

相关

计费与额度

消费如何计量、报价和设定上限。

安全与隐私

数据处理、保留策略与传输安全。