一键创建应用（NodeJS）

Node SDK 提供了 registerApp 方法，基于 OAuth 2.0 Device Authorization Grant（RFC 8628）协议实现一键创建应用。

调用该方法会返回一个验证链接，用户在飞书或 Lark 中打开该链接（或扫码）完成授权后，即可自动注册应用并获取凭据（App ID 和 App Secret），无需手动前往开发者后台创建。

查看源码：node-sdk

前提条件

• 安装 @larksuiteoapi/node-sdk，且 SDK 版本为 1.61.1 及以上。

  npm install @larksuiteoapi/node-sdk

快速开始示例

import * as lark from '@larksuiteoapi/node-sdk';

try {
    const result = await lark.registerApp({
        onQRCodeReady(info) {
            console.log(`请扫码: ${info.url}`);
            console.log(`链接将在 ${info.expireIn} 秒后过期`);
        },
        onStatusChange(info) {
            // 处理状态变化：'polling' | 'slow_down' | 'domain_switched'
        },
    });

console.log('App ID:', result.client_id);
    console.log('App Secret:', result.client_secret);

// 用获取到的凭据初始化 Client
    const client = new lark.Client({
        appId: result.client_id,
        appSecret: result.client_secret,
    });
} catch (e) {
    // e.code: 'access_denied' | 'expired_token' | 'abort' | ...
    // e.description: 错误描述
    console.error(e.code, e.description);
}

自定义权限/事件/回调（addons）与更新已有应用

创建应用时，可通过 addons 在平台基础模板上增量申请权限、事件订阅和回调，这些配置会预填到用户扫码后的确认页中，用户确认后生效：

// 创建：增量申请权限/事件/回调，且只允许创建新应用（不可选择已有应用）
const result = await lark.registerApp({
    addons: {
        scopes: { tenant: ['im:message:send_as_bot'], user: ['calendar:calendar:read'] },
        events: { items: { tenant: ['im.message.receive_v1'] } },
        callbacks: { items: ['card.action.trigger'] },
    },
    createOnly: true,
    onQRCodeReady(info) { /* ... */ },
});

// 更新：传入已有应用的 appId，让用户重新扫码确认，为该应用增量开通权限
await lark.registerApp({
    appId: 'cli_xxx',
    addons: { scopes: { tenant: ['drive:drive.metadata:readonly'] } },
    onQRCodeReady(info) { /* ... */ },
});

// 最小基座：丢弃默认模板（仅保留机器人能力，无业务权限），仅展示显式声明的配置项。
// 传入 `preset: false` 时，即使 addons 没有其他配置项也是合法的。
await lark.registerApp({
    addons: {
        preset: false,
        scopes: { tenant: ['im:message:send_as_bot'] },
    },
    onQRCodeReady(info) { /* ... */ },
});

• addons.preset 用于选择模板基座：true / 不传表示保留平台默认模板，并在其上叠加声明的配置项（增量，默认行为）；false 表示丢弃默认模板，从最小基座（仅机器人能力，无业务权限）开始，仅展示显式声明的配置项。仅当 preset: false 时 addons 可以不含其他配置项（最小基座、零增量），否则至少需包含一个权限、事件或回调。
• addons 仅支持在基础模板上增量叠加，不支持删减基础权限。
• 仅支持 5 类公开配置（应用/用户身份权限、应用/用户身份事件、回调）。敏感配置（事件订阅方式与回调地址、security.*、加密 key 等）不能通过 addons 传入，需调用更新应用开发配置 OpenAPI。
• SDK 只校验数据形状，不校验权限点/事件/回调名称是否存在；平台目录中不存在的名称会被确认页忽略。

registerApp 参数

返回值

错误处理

抛出的错误对象包含 code 和 description 字段：