---
title: "应用登记与回调"
description: "在组织所属项目中登记 Application，明确客户端类型、登录方式和允许的回调。"
url: "https://auth.kai.com/docs/applications"
language: "zh-CN"
version: "Better Auth 1.7.1"
updated: "2026-09-22"
---

# 应用登记与回调

在组织所属项目中登记 Application，明确客户端类型、登录方式和允许的回调。

## 登记入口与权限

路径为开发者控制台 → 组织 → 项目 → Applications。管理 API 位于 `/api/organizations/:organizationId/projects/:projectId/applications`，使用 KAI 登录会话和服务端权限检查。组织 owner、admin 和 developer 可以查看组织内项目并创建、管理应用；developer 的应用管理权限不包含项目管理。组织 member 需要显式加入该项目：项目 admin 可以管理项目及应用，项目 member 只能查看；未加入项目则不可访问。写操作还要求组织处于可用状态。

普通 public 应用的 PKCE 登录受到支持，与动态注册是独立能力；Discovery 列出的全局认证方法不代替已登记客户端的配置。OAuth Dynamic Client Registration 当前关闭。不要向 `/api/auth/oauth2/register` 发送请求以绕过控制台登记。

## 客户端配置

- **public**：不发放 client secret，令牌端点认证方式为 `none`。分发到浏览器、手机或 CLI 的共享 secret 无法保密。
- **confidential**：创建时返回一次 secret，令牌端点认证方式为 `client_secret_basic`。密钥保留在服务端，不能放入浏览器脚本、移动应用包或日志。
- 应用形态 `applicationKind` 与客户端类型分别登记：`web` 可以是 public 或 confidential；`native` 必须使用 public 和 PKCE，不能依赖分发到应用中的 secret。
- `authorization_code`、`device_code` 可单独或同时启用。浏览器授权至少登记一个 redirect URI；仅 Device Code 的应用可以不登记。
- 允许的 scope 为 `openid`、`profile`、`email`、`offline_access`，配置必须包含 `openid`。需要 refresh token 时申请并获准 `offline_access`。
- `requiredScopes` 是必须同意的权限，必须包含 `openid`；`optionalScopes` 由用户选择。两者不重复，合起来必须等于应用的 `scopes`。浏览器和 Device Code 授权都会展示这份策略，客户端必须处理用户未同意可选权限的情况。
- `members_only` 仅允许组织成员；`authenticated_users` 允许其他已登录用户。后者的 `organization_role` 可以是 `null`。

## 授权页展示资料

在项目设置中上传、替换或移除项目头像，并配置该项目的服务条款和隐私政策链接。应用可以配置独立头像；未设置时使用项目头像。图片会在浏览器裁剪压缩为 JPEG，后端再次检查图片格式与大小后保存。各应用还可以为已启用的 `openid`、`profile`、`email`、`offline_access` 分别填写用途，每项最多 500 字；用途不会增加应用能够申请的权限。

授权页展示应用名称、提供服务的组织名称，以及组织的「已验证」或「未验证」标记。KYB 只由平台管理员核验或撤销，组织或应用开发者不能自行标记。修改已验证的组织名称会自动使其变为未验证；该标记表示主体核验状态，不保证应用内容或行为。

项目政策链接改变时会增加政策版本。如果链接没有改变而政策正文更新，请在项目设置勾选发布政策更新；系统会检查当前版本，避免覆盖其他管理员的更新。

## 再次登录与自动登录

首次授权需要用户明确确认。再次登录时，授权页比较用户上次确认的资料，展示应用、组织、项目、头像、回调地址、资源、必需及可选权限、权限用途和政策版本的变化。已有的旧授权没有展示资料快照，会要求重新确认，不会默认开启自动登录。

用户勾选「下次自动登录」并完成授权后，之后相同资料的登录会展示五秒倒计时。取消倒计时会恢复拒绝与授权按钮；查看详情、修改勾选或离开可见页面也会停止倒计时。变化后的资料必须再次确认。用户可以在个人中心的已授权应用中关闭自动登录，或撤销整个应用授权。

自动登录偏好绑定当前账号与实际授权；撤销授权不会被旧偏好恢复。授权提交使用绑定账号、会话、完整签名请求和展示资料的一次性短期凭证，由服务端检查等待时间及最新配置。客户端仍只需要使用标准授权请求和已登记回调，不应自行调用 Auth 的页面确认接口。`prompt=consent` 始终要求确认；`prompt=none` 保持静默语义，无法完成时返回 OAuth/OIDC 错误，不会打开页面或自动扩大权限。

## 回调白名单

浏览器授权请求的 `redirect_uri` 必须匹配该应用登记的地址。使用明确的完整地址，不以任意 URL、域名通配或 `returnTo` 代替登记。Web 应用使用非 loopback 主机的 HTTPS 地址；原生应用另外支持 loopback HTTP 和应用拥有的反向域名 scheme。回调不能包含用户凭据、片段、通配符、空白或控制字符。

示例：

```text
redirect_uri = https://app.example.com/oauth/callback
post_logout_redirect_uri = https://app.example.com/signed-out
```

登录回调和退出后的地址分别登记，不能相互替代。每种回调地址最多登记 10 个。应用自己完成回调校验、换取令牌和建立应用会话，Auth 不负责把任意回调转换成不同终端能识别的链接。

## 移动端

在控制台选择原生应用和 public 客户端，可以登记开发者拥有的 HTTPS 回调，按操作系统规范把已验证链接交给应用处理；也可以登记 `com.example.app:/oauth/callback` 形式的反向域名 scheme，或 `http://127.0.0.1:端口/路径`、`http://localhost:端口/路径`、`http://[::1]:端口/路径` 形式的 loopback 回调。请求必须使用登记的回调及 PKCE；原生 loopback 回调允许临时端口变化，scheme、主机与路径仍须匹配。`kai://oauth/callback` 这类短 scheme 不属于新的登记契约。

`https://auth.kai.com/mobile/callback` 是旧 KAI App 的临时兼容端点，**已弃用**，最终转发到固定 `kai://oauth/callback`，不是通用移动端回调服务。尚未安排删除日期，新应用不要依赖它。

该端点只转发 OAuth 响应字段；缺少或重复必要字段会返回 400，裸地址也不是可启动的登录流程。它不会授权任何 Resource。

## 配置变更

修改必需或可选 scope 会撤销该应用已有的授权和待处理 Device Code，用户需要重新授权。用户缩减已同意的权限时，超出新范围的 access token 和 refresh token 会被撤销。

移动 Application 到另一个项目会保留 client ID 和 secret，但撤销现有 consent、待兑换授权码、access token 和 refresh token；用户需要重新授权，才能获得新的 `project_id`。离线验证的 JWT 可能在剩余有效期内继续被接受，详见[令牌校验与 claims](/docs/claims)。

## 控制台工作区

左上角工作区选择器列出已加入的组织及对应身份。没有组织时，可创建组织或查看发送至已验证邮箱的待接收邀请。平台管理员可另外查看全平台组织目录；平台身份不等于组织成员身份，也不自动授予项目访问权。

组织内先选择项目，再进入应用。组织概览和项目概览用于定位工作，名称、品牌、头像及协议在各自的设置页面维护。应用配置分为登录设置、数据与权限、客户端凭据、测试与诊断四个选项卡；项目头像和协议由项目内应用共享，应用仍可配置自己的头像和每项 scope 的用途。

在测试与诊断中打开 OAuth 测试页，会预填公开 Client ID 和客户端类型。私密 Web 的密钥需要在测试页输入，不会写入 URL。测试页要求的回调地址必须先加入应用的回调白名单。API 资源与应用的授权关系在项目的 API 资源页面管理，详见[资源、scope 与访问令牌](/docs/resources-and-tokens)。

停用应用会阻止新授权并撤销已有授权；重新启用后需要重新授权。修改设置后请保存；跨组织、项目或应用离开有未保存修改的页面时，控制台会要求确认。