Lark Bitable APIでフィールド追加がPermission deniedになる原因と回避策

Lark Base（Bitable）でフィールドを増やそうとしてAPIを叩いたら、こんなレスポンスが返ってきました。

{
  "code": 1254302,
  "msg": "Permission denied",
  "data": {}
}

奇妙なのは、レコードのCRUD（作成・更新・検索・削除）はまったく問題なく動いていることです。データの読み書きは通るのに、フィールドを1本足すAPIだけが弾かれる。コードは間違っていないのに、です。

これはLark Bitableで業務システムを組もうとした多くのチームが一度はぶつかる壁で、原因はコードではなくスコープ（＝アプリに許可された操作範囲）の設計にあります。この記事では、まず原因と最短の回避策を示し、後半で「Larkで業務システムを作る前にスコープをどう確認すべきか」という、内製・外注を判断する人向けの材料をまとめます。

結論：レコード操作とスキーマ操作は別スコープ

原因はシンプル。Lark Bitableの権限は、データ（レコード）を操作する権限と、テーブルの構造（スキーマ）を変える権限が、別々のスコープに分かれています。

• レコード操作系のスコープだけでは、フィールドの追加・削除・型変更はできない
• スキーマ変更には bitable:app（フルアプリ権限）が必要
• bitable:app の付与にはテナント管理者の承認が要り、即日では下りないことが多い

なお、同じPermission deniedは、アプリがそのBaseの共同編集者になっていない場合や、Baseの「高度な権限」が有効で管理権限が無い場合にも出ます。スコープを直しても解消しないときはそちらを疑ってください。また、スコープの正式名称と粒度は更新されることがあるので、実名はLark Developer Consoleの権限一覧で確認してください。

つまり「レコードを書けるならフィールドも書けるはず」という直感が外れます。Lark側は、業務データの書き込みと、テーブル構造の変更を、わざと別のレイヤーとして扱っているからです。

回避策は大きく3つあります。スコープ拡張を申請する、手動UIとAPIを役割分担させる、別アプリを新規に作る。当日中に動かしたいなら2番目が現実解になります。詳しい使い分けは後述します。

Lark Bitable APIのスコープ早見表

Bitable関連でよく見るスコープの違いを整理します。ここを最初に押さえておけば、Permission deniedで半日溶かすことはなくなります。

表のとおり、フィールド操作を伴う作業は bitable:app がないと一歩も進みません。逆に言えば、データを入れたり更新したりするだけならレコード操作系のスコープで足りるので、最初に「自分のやりたいことはデータ操作なのか、構造変更なのか」を切り分けるのが先決です。

このスコープ分離はセキュリティ上は理にかなっています。「アプリAはデータ入力だけ、アプリBは構造管理だけ」と責務を分けられるからです。とはいえ、1つのアプリで全部やろうとした人が最初にハマるのもここで、合理性と使いにくさが同居しています。

実話：レコード紐付け作業の最後の一歩で止まった

具体例を書きます。あるテーブルに「YouTubeリンクのLookup列」を複数本追加して、既存の十数件のレコードに紐付けるタスクがありました。Lookup列＝別テーブルの値を参照して表示する列のことです。

作業を進めると、こうなりました。

• レコードのbatch_updateで十数件を紐付け：あっさり動く（レコード操作系のスコープで足りる）
• フィールドを複数本追加するAPI：全部 Permission denied

タスクの大半は自動化できているのに、最初の「列を作る」一手だけが手動UIに戻されたわけです。これがLark Bitableで自動化を組むときの典型的な制約で、知らずに「全部APIで回します」と設計すると、最後の一歩で立ち止まります。

ここで重要なのは、止まったのが珍しいケースではないという点です。スキーマ変更を含む作業は、最初から手動UIが混じる前提で設計しておくのが普通です。

回避策3パターン

止まったあと、選べる道は3つあります。状況によって使い分ける。

パターン1：bitable:app スコープを拡張する（中長期向き）

正攻法はスコープの拡張です。Lark Developer Consoleで該当アプリを開き、スコープを追加し、新バージョンをリリースして、テナント管理者の承認を待ちます。

ただし承認が下りるまでの時間はテナントの運用次第で、その日のうちに動かしたいタスクには間に合わないことが多くなります。同じ種類の作業がこの先も続くなら、早めに申請しておくのが正解。単発なら次のパターン2に逃がすほうが速い。

パターン2：手動UIとAPIのハイブリッド（当日の現実解）

スコープ拡張を待たずに進めるなら、操作を役割で分けます。

1. フィールドの追加・削除・型変更：ユーザーが手動UIで実施（数十秒から数分で終わる）
2. レコードのCRUD・データ紐付け：APIで自動化

手動UIの操作は基本的に1度きりなので、自動化しないコストは小さい。一方でレコード操作は件数が膨らみがちなので、APIで自動化する効果が大きい。この分業を最初から前提に置けば、「スコープが足りなくて詰む」事態そのものを避けられます。先ほどの実話も、結局この形に落として完了しました。

パターン3：別アプリを新規作成して bitable:app 込みで申請

新規プロジェクトなら、最初から bitable:app を含むスコープでアプリを作ってしまうのが楽です。既存アプリのスコープ拡張は管理者承認を待つことになりますが、新規作成は自社で完結できる場合があります（テナント全体のアプリ作成権限が必要）。

ただし認証情報を二重に持つことになるので、用途がはっきり分かれているときだけ採用します。むやみにアプリを増やすと、後で誰がどのトークンを使っているか分からなくなる。

なお、ここまで挙げたスコープはあくまで「構造を変える」話です。レコードの読み書きでLark Bitableを業務データベースとして使う設計そのものは別記事にまとめてあります。Lark Bitable APIで業務データベースを構築する手順が「できること」側、本記事が「できないことと回避」側で、2本セットで読むとスコープの全体像がつかめます。

スコープ拡張を申請するときの手順

パターン1や3で bitable:app を申請する場合、Lark Developer Consoleでの流れはこうなります。

1. Developer Console で該当アプリを開く
2. 「権限とスコープ」タブに移動する
3. bitable:app を検索して追加する
4. 「バージョン管理とリリース」で新バージョンを作成する
5. リリース申請を出し、テナント管理者の承認を受ける

申請理由欄には具体的な利用シーンを書きます。「スキーマ変更を自動化するため、Lookup列の追加削除をAPIで実施する必要がある」のように、なぜそのスコープが要るのかを明示しないと、管理者は承認の判断ができません。理由が薄いと差し戻され、また待つことになります。

承認後にもう1つ落とし穴があります。既存のAccess Tokenを発行し直さないと、新しいスコープが反映されないことです。tenant_access_token を取り直してから、改めてAPIを叩いてください。

ここまでが「今ぶつかっている人」向けの解決策です。ここからは、これからLarkで業務システムを作る人・外注する人が、同じ壁を踏まないための判断材料に移ります。

業務システムを作る前のスコープ確認チェックリスト

Lark Bitableで何かを内製・外注する前に、次を確認しておくと、設計の後半でスコープに足を取られずに済みます。着手前の数分で、後の手戻り半日を防げます。

• やりたい操作はデータ操作か、構造変更か（レコードの読み書きだけならレコード操作系のスコープ、列やテーブルをいじるなら bitable:app）
• 構造変更を自動化したいか（自動化したいなら bitable:app 必須。手動UIで済むなら申請不要）
• bitable:app の承認に誰のハンコが要るか（テナント管理者が誰で、承認に何日かかるか）
• 当日納期のタスクがあるか（あるなら手動UIとAPIのハイブリッド前提で設計する）
• アプリを分けるべきか（データ入力用と構造管理用で責務が分かれるなら別アプリも検討）
• トークンの種類と再発行手順を把握しているか（tenant_access_token の取り直しが必要になる場面がある）

このチェックリストの肝は最初の2項目です。「データを入れたいだけ」なのか「構造ごと自動で変えたい」のかで、必要なスコープも承認の有無もまるごと変わる。ここを曖昧にしたまま「Larkで全部自動化します」と進めると、後半でほぼ確実に止まります。

APIでできる・できない早見表

自動化の計画を立てる人向けに、Lark Bitable APIで「自動化できる作業」と「手動UIが混じる作業」を分けておきます。発注前の工数見積もりの土台になります。

この表で見えるのは、「データ操作は自動化向き、構造変更は手動UIが混じりやすい」という線引きです。計画段階でこの線を引いておけば、「列追加まで全部APIで」という非現実的な見積もりを出さずに済みます。

外注するときの確認項目

Lark業務システムを外注する場合、スコープまわりは見積もりの精度を左右します。発注前に外注先へ確認しておきたいのは次の3点です。

• スキーマ変更を自動化に含めているか：「列の追加もAPIで自動化します」という見積もりは、bitable:app 承認の段取りまで織り込まれているか確認する。織り込まれていないと、納品間際に「スコープが下りないので手動で」と差し戻される
• テナント管理者承認の段取りを誰が持つか：承認の依頼は社内側でしか出せない。誰がいつ申請し、何日見ておくかを発注前に握る
• トークンと認証情報の管理方針：別アプリを増やす設計なら、トークンが二重持ちになる。どのトークンが何用かを一覧化して納品物に含めてもらう

この3点を最初の打ち合わせで詰めておくと、「全自動化できます」という景気のいい提案が、実態に合っているかどうかを見抜けます。Larkに限らず、スコープや権限の段取りを軽く扱う見積もりは、後半で崩れます。

アンチパターン3つ

実際の現場で起きた、避けたい振る舞いを3つ挙げます。自社で組む人にも、外注先を選ぶ人にも効く。

アンチパターン1：全自動化を提案してから「スコープが足りなくて」と差し戻す

新規のBitable連携を提案するとき、最初から「手動UIとAPIのハイブリッド前提」で工数を見積もるのが正解です。「全部自動化できます」と言ってからスコープで詰まると、信頼を一気に失います。できないことを先に正直に伝えるほうが、結果的に評価されます。

アンチパターン2：Permission deniedをコード番号だけで片付けて記録しない

1254302 というエラーコードは、Lark公式のエラーコードリファレンスを引かないと意味が分かりません。原因がスコープ不足だと突き止めたら、それを自分のメモに残しておく。これをやらないと、半年後に同じ罠へ二度目のダイブをして、また半日を溶かします。

アンチパターン3：tenant_access_tokenを再発行せずに「スコープが反映されない」と騒ぐ

スコープ拡張が承認されたら、必ず tenant_access_token を新規発行してからテストします。古いトークンは古いスコープのままで動くので、「承認したのに反映されない」と無駄に騒ぐことになります。承認とトークン再発行はセットだと覚えておけば防げます。

まとめ：Lark Bitableは「データ操作」と「構造変更」が別世界

Lark Bitable APIで業務システムを組むときの基本原則は、次の3つに尽きます。

1. レコード操作系のスコープではフィールド操作はできない。構造を変えるなら bitable:app が要る
2. bitable:app の拡張にはテナント管理者の承認待ちが発生する。当日納期には間に合わないことが多い
3. 手動UIとAPIのハイブリッド設計を、計画の最初から織り込む

この線引きを着手前に引いておけば、「全自動化を提案してから差し戻す」事故も、「Permission deniedで半日溶かす」事故も防げます。Larkを業務システムとして使う組織なら、最初の打ち合わせでスコープの話をするのが鉄則。それだけで、後半の手戻りがほぼ消えます。

Lark業務システムのスコープ設計でお困りなら

「Larkで業務を回したいが、どこまで自動化できてどこから手動が混じるのか分からない」。そう感じる担当者は多いはずです。Lark Bitableはスコープ設計・Automation設定・外部システム連携の3点で詰まりやすく、ここを最初に整理しておくかどうかで、後の手戻り工数が大きく変わります。

f2t.jpでは、Larkで何を自動化できて何が手動に残るかの線引きから、スコープ申請の段取り・外部API連携の設計まで一貫してお手伝いしています。まずは「自社のやりたい操作に必要なスコープ・承認の段取り・自動化できる範囲」を一緒に整理するところから始められます。お問い合わせフォームから、自社のLark活用についてご相談ください。