身份验证

Kisenon 提供两种身份验证方式：

Web 登录 —— 通过控制台上的 NextAuth 使用 Google 或 GitHub OAuth。
API 密钥 —— 一个 nsk_… 令牌，任何 HTTP 客户端（包括 keon）都可以将其作为 Bearer 凭据出示。

同一个密钥可以驱动 CLI、CI 以及一次性的 curl 调用。

Web 登录

打开 kisenon.com 并点击 Sign in。选择 Google 或 GitHub。NextAuth 负责处理 OAuth 交互流程，然后通过 POST /v1/auth/exchange 将提供方的 id 令牌换取一个控制平面 JWT。该由 cp 签发的 JWT 就是后续每个控制台请求所携带的凭据。

该 JWT 存续期很短 —— 大约在签发后 15 分钟过期。在你处于活跃状态时， NextAuth 会在后台通过将当前 JWT 重新出示给 POST /v1/auth/refresh 来刷新它，从而铸造一个新的。刷新凭据就是 JWT 本身，自登录起在 12 小时窗口内有效；一旦该窗口失效，下一个请求就会将你重定向到登录页面。

访问

使用 Google 或 GitHub 登录。当开放注册启用时，新账户可立即使用：首次交换会创建你的用户和一个个人组织，然后你会直接进入控制台。

在我们进行接纳期间，访问可能会受到限制 —— 这是运维方可以按环境切换的一个开关。当它开启时，已经登录但尚未启用的账户会进入 pending 状态：控制台会将其重定向到 /pending，控制平面会以 403 alpha_pending 回应受门控的 API 调用，直到该账户被启用。已配置的登录白名单也可以在签发任何会话之前，以 403 email_not_allowed 拒绝未列入白名单的账户。

组织和角色

身份以组织为先。每个会话都携带一个活跃组织以及你在其中的角色（例如 owner 或 member）；cp JWT 对两者都进行编码，控制平面会在每次刷新时重新读取你的角色。个人注册会自动获得一个个人组织；受邀用户在首次登录时进入团队组织。

如果你属于多个组织，控制台中的组织切换器（位于登录后布局的顶部）会将它们连同角色徽章一起列出。选择其中一个会向 /api/auth/switch-org 发起 POST，它会代理到 cp 的 /v1/auth/switch-org，并将一个新的 JWT —— 作用域限定为新组织 —— 拼接进你的会话。切换之后，所有控制台请求都会在所选组织中执行。

参见组织了解组织和角色的工作方式，以及邀请了解如何添加团队成员。

API 密钥

API 密钥是以 nsk_ 为前缀的凭据。每个密钥：

采用 nsk_<random> 格式，并且在创建时仅显示一次 —— 它在静态存储时经过哈希处理，因此我们之后无法恢复其明文。请立即保存或对其进行轮换。
在其作用域内以你的身份行事。
可以随时被吊销，且不影响其他密钥。

从控制台铸造密钥

在设置 → API 密钥铸造密钥。每一行都会显示密钥的名称、id、创建日期以及最近一次使用的时间。创建表单有四个字段：

Name —— 一个标签，最多 64 个字符。
Capability —— 见下文。
Scope —— 见下文。
Expires (days) —— 留空表示永不过期的密钥。

提交后，密文会仅显示一次。在关闭对话框之前将其复制。

Capability 决定密钥可以做什么：

read_write（默认）—— 完整的读取和写入。
read —— 只读；任何变更调用都会被拒绝。
agent —— 可以驱动沙箱，但不能获取可写的 main 凭据。将此能力交给 AI 智能体，使其针对分支操作，而永远不会触及生产环境的 main。参见智能体安全变更控制。

Scope 决定密钥可以触及什么：

组织（默认）—— 活跃组织中的所有内容。
一个特定项目 —— 限定于该项目；对任何其他资源的请求都会得到 403 scope_insufficient。（通过 API 也支持分支作用域。）

创建密钥需要一个已登录的浏览器会话 —— 一个 nsk_ 密钥不能铸造另一个密钥。密钥可以吊销自身，但一个 nsk_ 持有者只能自我吊销；它不能删除其他密钥。

通过 API

同样的操作在 cp 的 /v1/api-keys/ 端点上可用：POST 一个 name、scope 和 capability 以创建，响应会携带一次性的密文密钥。

IP 白名单

每个项目都可以携带一个由 CIDR 组成的网络白名单。当该列表被设置时，只有源自列出的 CIDR 的连接才能到达该项目的端点；强制执行覆盖唤醒路径，因此未列入白名单的客户端也无法唤醒一个已挂起的端点。空白名单意味着没有 IP 限制 —— 所有来源都被允许。

从 CLI 管理该列表：

keon ip-allow add 203.0.113.0/24 --project prj_abc...
keon ip-allow list --project prj_abc...
keon ip-allow remove 203.0.113.0/24 --project prj_abc...

或通过 API：

GET /v1/projects/{projectId}/ip-allow —— 列出当前规则。
POST /v1/projects/{projectId}/ip-allow —— 添加一条规则。请求体为 {cidr, label, ttl_seconds?}；ttl_seconds 是可选的，可使规则自动过期。格式错误的 CIDR 会返回 422。
DELETE /v1/projects/{projectId}/ip-allow/{cidr} —— 移除一条规则。
DELETE /v1/projects/{projectId}/ip-allow —— 重置整个列表。

强制执行在代理处进行，它大约每 30 秒刷新一次其视图，因此一次更改会在几秒内传播。

CLI 回环 OAuth

keon login 不会要求你粘贴 API 密钥。相反，它会运行一个回环 OAuth 流程：

CLI 在一个随机高端口上启动一个本地 HTTP 监听器。
它打开你的浏览器访问 https://kisenon.com/cli/authorize?...，附带一个一次性 state 令牌和回环重定向 URL。
你登录（或已经登录）并点击 Authorize。
控制台会带着一个短期 code 重定向到回环 URL。
CLI 在 POST /v1/cli/exchange 处将该 code 换取一个新铸造的 API 密钥。
该密钥以 0600 模式持久化到 ~/.config/keon/credentials.json。

流程结束后，keon whoami 确认密钥已就绪：

keon login
keon whoami

CLI 不会存储 OAuth code、state 或任何提供方侧的令牌；仅存储最终得到的 API 密钥。你可以随时从控制台对该密钥进行轮换或吊销。

登出

keon logout 会在服务器上吊销本地 API 密钥并删除凭据文件。登出后，同样的 keon login 流程会铸造一个新密钥 —— 旧凭据无法被重新激活。

keon logout

控制台登出会清除浏览器会话并重定向到落地页；它不会吊销你通过 CLI 铸造的 API 密钥。使用 设置 → API 密钥 来逐个吊销那些密钥。

来自任意客户端的 Bearer 身份验证

任何能够使用 HTTP 的客户端都可以访问控制平面：

curl -H "Authorization: Bearer $KISENON_API_KEY" \
  https://api.kisenon.com/v1/projects

bearer 令牌要么是一个 API 密钥（nsk_…），要么是一个通过 /v1/auth/exchange 签发的由 cp 签名的 JWT。对于组织作用域的端点，两者是等价的。