项目与密钥 | Glac 文档

账户负责付款、拥有成员，并在经过验证的地址接收通知；其余一切都在它的项目中。API 密钥属于一个项目，有各自的权限范围；令牌只能打开一个沙箱；控制台负责人员登录。

账户与成员

账户是付款的主体：它有一个套餐、余额和成员。每个成员的角色是 owner、admin 或 member：

角色	能做什么
`owner`	一切：账户的计费和成员管理，以及关闭账户。账户总有一个所有者。
`admin`	除计费和所有者之外的一切：在项目中与所有者权限相同；邀请和移除管理员及成员，修改他们的角色。
`member`	项目，以及项目中的沙箱、方块和密钥（不含 `admin` 权限范围）。

人员用邮箱地址和密码登录[控制台](https://console.glac.ai/console/)，或者在控制台显示相应按钮时用 GitHub 或 Google 登录；接受账户的邀请也是同样的方式。一个账户有一个或多个项目。

通知发往哪里

账户的通知会发到它的地址。用 glac account email ADDRESS（或调用 PATCH /v1/account 并带上 email，需要 admin 权限范围）设置，或在控制台 Billing 页面的 Mail 部分设置，那里还会列出发给账户的每一封邮件及其内容（GET /v1/billing/notices、glac billing notices）。

只给已验证的地址发邮件（GET /v1/account 的 email_verified）。如果账户之前已验证过这个地址，或者它是账户某个成员已验证的地址，就立即视为已验证。其他地址会收到一封带验证链接的邮件，链接 7 天内有效，在链接被打开之前，账户的通知都会暂缓发送。再次设置地址（即使是同一个）会发出新的链接，旧链接随即失效；控制台中的 Send the link again 也一样。每个账户先可以发三次链接，之后每十分钟一次 (429 rate_limited)。
被退回的邮件。一旦发往该地址的邮件被退回，或者收件人把它标记为垃圾邮件，就不会再有通知发往那里（email_undeliverable：why 为 bounced 或 complained，并附有 since 和发件方的 detail）。通知会暂缓发送，直到重新设置地址（即使是同一个）。
通知暂缓期间，任何从通知起算的期限都不会开始：欠费账户存储的内容被删除前的 30 天，是从关于欠款的第一封通知送达时开始计算的。
修改自己地址的成员，会把原来发往旧地址的、他所属账户的通知一起带到新地址。

会发送的邮件：

通知	情形
`purchase_confirmed`, `withdrawal_received`	一笔购买（充值、套餐）；对购买的撤回，回执发往撤回时给出的地址。
`included_80`, `included_100`, `storage_80`, `storage_100`	没有余额、自动充值也不会为其充值的账户，某个计量项或存储已用到套餐包含额度的 80%，然后是全部。
`in_debt`、`reminder_…`（按天）、`charge_failed`、`data_deleted`	账户因存储而欠费；在第 7、14、21、27和29 天各发一次提醒；从银行卡扣除欠款失败；存储的内容已被删除。参见欠费的账户。
`subscription_charge_failed`, `subscription_ended`	套餐续费扣款失败；宽限期内没有付款，账户已转为免费版。
`reload_failed`, `reload_no_card`, `reload_no_request`	自动充值扣款失败、没有银行卡，或在等待买方的要求。
`credits_expiring_…`（按剩余天数）	部分点数将在 30、7和1 天后过期。
`tax_address_confirm`, `tax_payment_held`	账单地址需要确认；某笔付款被暂扣，等待支持团队处理。
`account_held`	账户已被冻结：参见 `account_held`。
`verify_account_email`	验证地址的链接，发往该地址。

项目

其余一切都在项目中：它的密钥、方块、沙箱、快照、云盘和存储卷、机密、共享变量和域名。名称在项目内唯一。密钥只能看到它自己的项目。

GET /v1/project (glac project) 给出密钥所属的项目：id、名称、归属区域、私有网络的地址段，以及沙箱休眠多少天后被删除（调用 PATCH /v1/project 并带上 delete_after_idle_days，或 glac project --delete-after-idle-days 30：参见休眠太久会被删除）。项目可以有自己的每月支出上限：参见支出上限。

服务

每个方块都是其项目中的一个服务。服务在项目的私有网络上互相发现，共享变量，一起部署，把数据保存在自己的云盘上，还可以从 Compose 文件导入：参见服务与 Compose。

API 密钥

密钥 (ak_…) 属于一个项目，有各自的权限范围。在控制台的 API keys 页面创建，或者用 POST /v1/keys 创建（{name, scopes, expires_at}，每个字段都可选；glac keys create，Python 中为 glac.keys.create()）。密钥只显示一次，就在创建它的响应中：请妥善保存。没有选择权限范围的密钥拥有除 admin 以外的所有权限范围。DELETE /v1/keys/{id} 立即吊销一个密钥。

权限范围	开放的权限
`read`	读取沙箱、快照、云盘和存储卷、用量、账户、账单、事件、方块、项目及其变量；机密的名称。
`write`	创建、修改和删除沙箱、快照、云盘、存储卷和方块；休眠、重启、分叉、恢复；部署和回滚；共享变量。
`exec`, `files`, `tty`, `url`	运行命令、文件、终端、端口链接。
`admin`	密钥、SSH 密钥、Webhook、支出上限、审计日志、账户设置、计费和充值、机密和域名。

权限范围不足以执行调用的密钥返回 403 key_scope；过期的密钥返回 401 expired_api_key。

每个工具都读取同样的两个环境变量：

export GLAC_API_URL=https://api.glac.ai
export GLAC_API_KEY=ak_...

其他凭据

单个沙箱的令牌 (st_…) 只能打开那一个沙箱，带有 url、exec、files 和 tty 中的部分权限范围，默认有效一小时：参见令牌。
SSH 密钥通过 SSH 网关打开项目中的沙箱：参见 SSH。

API 如何响应

输入和输出都是 JSON，使用 snake_case，时间采用 RFC 3339 格式，大小以字节为单位 (_bytes)，时长以秒 (_seconds) 或毫秒 (_ms) 为单位。id 带有类型前缀：sbx-、exe-、snap-、vol-、app-、ver-。凡是接受 id 的地方，也接受名称。
错误都是同一种格式：{"error": {"type", "code", "message", "param", "retryable", "request_id", "docs_url"}}。code 给程序看，message 给人看；retryable: true 表示稍后再次调用可能成功，知道何时重试时带有 Retry-After；docs_url 指向错误页面上对应的错误码。每个响应都带有 X-Request-Id。
列表分页返回：?limit=（1 到 1,000，默认 100）和 ?cursor=（取上一页的 next_cursor），最新的在前。
Idempotency-Key 用于 POST（1 到 255 个字符）：24 小时内用同一个键和同样的请求体再次发送，会得到第一次的响应，任何操作都不会执行两次。SDK 会为每个 POST 发送一个。
事件：GET /v1/events 列出项目中发生的事情（sandbox.created、drive.attached、balance.used_up 等），Webhook 会把它们投递到你的 URL，并用 Webhook 的机密签名（POST /v1/webhooks、glac webhooks create，Python 中为 glac.webhooks.create()）。GET /v1/audit 列出谁改了什么：每一次不是读取的调用（被拒绝的也算）及其发起者，以及运营方对应用日志的每一次读取（glac audit、SDK 的 audit、MCP 服务器的 project_audit；需要有 admin 权限范围的密钥）。

API 参考列出了所有调用。