BitLayout OAuth Guide
設定 飛書 自建應用
依照以下步驟在 飛書開放平台 建立企業自建應用，取得 App ID 與 App Secret 後，即可回到 BitLayout 完成授權登入。
LinkedRecord 使用提醒
若 Bitable 表格含有跨表引用欄位，請使用 Lark 的「關聯欄位（LinkedRecord）」再搭配 Lookup 顯示帶出欄位， 不要用兩個 single-select 欄位互相做 Lookup filter。後者會被 Lark API 視為不可寫欄位，BitLayout 提交時會回 `LARK_LINKED_FIELD_NOT_WRITABLE`。
1
2
建立企業自建應用
點擊「建立應用」並選擇「企業自建應用」。
填入應用名稱（例如：BitLayout）與簡短描述後點擊「建立」。
i
提示
建立完成後會進入應用主控台，左側選單就是後續權限、機器人與安全設置的入口。
3
取得 App ID 與 App Secret
在左側選單點擊「憑證與基礎信息」。
找到 App ID（格式：cli_xxxxxxxxxx）與 App Secret，點擊「查看」後複製。
i
安全提醒
App Secret 請妥善保管，不要公開分享，也不要提交到版本控制系統。
4
開啟機器人能力
在左側選單點擊「應用功能」→「機器人」，啟用機器人開關。
這是群組搜尋權限 im:chat:readonly 能正常運作的前提。
!
注意
若未啟用機器人，群組類型欄位將無法使用，提交時可能出現權限錯誤。
5
開通 API 與 OAuth 權限
在左側選單點擊「權限管理」。
將下方 JSON 中 scopes.tenant 陣列的內容逐一搜尋並開通於「API 權限」頁籤。
將 scopes.user 陣列的內容逐一搜尋並開通於「OAuth 權限」頁籤。
點擊下方「複製 JSON」按鈕可一鍵複製完整設定清單，方便對照。
JSONscope-config.json
{
"_說明": "在 Lark 開發者後台「權限管理」→「API 權限」與「OAuth 權限」頁籤中，分別貼上對應陣列的 scope 即可。",
"scopes": {
"tenant": [
"base:app:read",
"base:table:read",
"base:field:read",
"base:record:read",
"base:record:retrieve",
"base:workspace:list",
"drive:drive",
"drive:drive.metadata:readonly"
],
"user": [
"bitable:app",
"base:app:read",
"base:table:create",
"base:table:read",
"base:field:create",
"base:field:read",
"base:record:create",
"base:record:read",
"base:record:retrieve",
"base:record:update",
"base:workspace:list",
"drive:drive",
"drive:drive.metadata:readonly",
"im:chat:readonly",
"contact:user.base:readonly",
"contact:user.email:readonly",
"offline_access"
]
}
}!
drive:drive 注意
請勿只開通 drive:drive:readonly，附件上傳需要完整的 drive:drive 寫入權限。
6
設定重定向 URI
在左側選單點擊「安全設置」，找到「重定向 URL」區塊，點擊「添加」並填入下方網址。
https://bit-layout.com/api/auth/callbacki
重要
Redirect URI 必須完全一致，包含 https 與完整路徑，否則 OAuth 授權會失敗。
7
建立版本並發布
在左側選單點擊「版本管理與發布」→「建立版本」，填入版本說明後點擊「申請發布」。
部分企業需要管理員審核，審核通過後應用才會正式生效。
ok
發布提醒
如果之後修改 scope 或 Redirect URI，記得重新建立版本並再次發布。
完成後，回到 BitLayout 填入以下資訊
Base URL
https://open.feishu.cn
App ID
cli_xxxxxxxxxx
App Secret
••••••••••••