认证与密钥

Favonis API 用 API 密钥认证：每个请求都在请求头 Authorization 中带上 Bearer 和密钥，REST 和 MCP 都是如此。密钥在 Favonis 的 设置 → 开发者 → API 密钥 中创建，以 fvk_ 开头，属于创建它的人，以创建时所在空间里的身份调用接口、扣除积分。

发送密钥

curl https://api.favonis.com/v1/me \
  -H "Authorization: Bearer fvk_..."

未带密钥，或者密钥无效、已过期、已删除时，返回 401 和 error.invalid_token。只有 GET /v1/openapi.json 不需要密钥。

密钥代表谁

在个人空间创建的密钥代表你的个人账号，在团队空间创建的代表你在该团队中的成员身份。

积分由这个空间支付：个人空间扣你的积分，团队空间扣团队积分，团队成员的每期积分上限照常生效。
只能访问这个身份下的任务、项目和文件，看不到团队里其他成员的内容，与应用中一致。
同时运行的任务数的上限由这个空间的套餐决定，只计这个身份下的任务。
密钥数、Webhook 地址数和请求频率都按这个身份计算，团队里的每位成员各有一份，互不占用。
你离开团队时，你在这个团队中创建的密钥和 Webhook 地址一并删除，之后用这些密钥发出的请求返回 401 和 error.invalid_token。

账号被封禁时返回 403 和 error.user_banned；密钥所属的空间无法使用时，返回 403 和 error.account_unavailable。

创建密钥时的选项

创建密钥需要先完成实名认证，并在弹出确认是你本人时验证身份。你在每个空间中最多有 20 个密钥。

选项	说明
名称	1 到 60 个字，用来区分不同的程序
权限	完全访问或只读。只读密钥只能调用 `GET` 接口，在 MCP 中只能使用查看类的工具；调用会修改内容或消耗积分的接口时返回 `403` 和 `error.api_key_read_only`
每月积分上限	这个密钥发起的任务每月最多消耗多少积分，见下一节；不设置时不限。只读密钥不消耗积分，不设这一项
有效期	永不过期（默认）、30 天、90 天或 1 年；过期后返回 `401` 和 `error.invalid_token`

创建后可以修改名称和每月积分上限。权限和有效期不能修改，需要时新建一个密钥，再删除旧的。

每月积分上限

每月积分上限按北京时间的自然月，统计这个密钥发起的任务已结算的积分。达到上限后，用这个密钥新建任务和发消息（包括补充说明、回答提问、继续暂停的任务）都会返回 403 和 error.api_key_monthly_cap_reached；已在运行的任务照常完成，因此当月的实际消耗可能略高于上限。下个月 1 日起恢复。

上限只约束这一个密钥。空间的积分用完时，请求不会因此失败，任务会暂停，见积分用完时。

查看账号和用量

GET /v1/me 返回密钥代表的账号、空间的可用积分，以及这个密钥本月已消耗的积分：

{
	"id": "0195e1c0-8a4f-7b21-9d3e-2c7f5a10b864",
	"name": "林晓",
	"workspace_id": "0195e1c0-8a4f-7b21-9d3e-2c7f5a10b864",
	"points": 52340,
	"key": {
		"id": "0196a1d0-3f2b-7c84-b5e9-1a6d8e2f4c07",
		"name": "报表系统",
		"read_only": false,
		"monthly_cap": 20000,
		"month_points": 6420
	}
}

workspace_id 是付款的空间：个人空间里和 id 相同，团队空间里是团队。monthly_cap 为 null 表示不限。

保管密钥

密钥只在创建时显示一次，之后只显示开头几位，供你辨认。
把密钥放在服务端的环境变量或密钥管理服务里，不要写进网页前端、移动应用安装包或代码仓库。
不同的程序使用不同的密钥，并为它们设置每月积分上限，出问题时只需删除其中一个。
怀疑密钥泄露时，立即在 设置 → 开发者 → API 密钥 中删除它。删除后，使用它的请求立即被拒绝。

通过密钥发起的操作视为你本人的操作，积分照常扣除，见《Favonis API 使用规则》。