Lark Bitable APIでフィールド追加できない原因｜Permission deniedの対処法

Lark Bitable APIでフィールドを追加しようとして「Permission denied（code 1254302）」が返るとき、まず疑うのはBaseの「高度な権限」です。公式の説明では、1254302は呼び出し元にBaseの高度な権限が無いときのエラーです。多くの場合、Baseで高度な権限が有効になっていることが背景にあります。公式が案内する対処は、データ表またはBaseの「管理」などの権限を与えることです。アプリなら、Baseのメニューから文書アプリとして追加して権限を与えます。筆者の環境では、レコードの読み書きは通り、フィールドの追加だけが弾かれました。当日中に進めたいなら、フィールドだけ画面から手で追加し、データの読み書きをAPIに任せる分担が現実的です。

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

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

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

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

結論：1254302は高度な権限が無いときのエラー。データ表かBaseの「管理」などの権限を与える

Lark公式のAPIリファレンスが前提条件に挙げているのは、呼び出し元がBaseの「編集」などの文書権限を持っていることです。これはフィールド作成もレコード作成・更新も同じで、フィールドだけに「管理」を求める記述はありません。差が出るのは、多くの場合、Baseで高度な権限が有効になっているときです。Lark公式のフィールド作成APIリファレンスのエラー表をもとに、疑う順に並べます。

• 原因1：呼び出し元にBaseの高度な権限が無い。公式の説明では、1254302はこの状態で返るエラー。多くの場合、Baseで高度な権限が有効になっていることが背景にある。公式の対処は、データ表またはBaseの「管理」などの権限を与えること。フィールドだけでなく、レコード作成・更新のエラー表にも同じコードが載っている
• 原因1の直し方（アプリとして呼ぶ場合）：先にアプリでBitable系のAPIスコープを1つ以上有効にしておく。そのうえでBaseの「…」から、その他のメニュー、文書アプリの追加と進んでアプリを追加し、「管理」権限を与える（手順はパターン1で詳しく書きます）
• 原因1の直し方（ユーザーとして呼ぶ場合）：user_access_token で呼ぶなら、そのユーザー本人がBaseで「管理」などの権限を持っている必要がある（高度な権限の設定で役割を付ける方法もある）
• 原因2：アプリのスコープが足りない。フィールド作成には bitable:app か base:field:create が要る。公式ではどちらか1つで足りるとされている

アプリがAPIの権限（スコープ）を申請していない場合は、1254302ではなく99991672が返ります（公式の汎用エラーコード一覧）。1254302が出たら、まずBaseで高度な権限が有効か、呼び出し元にデータ表またはBaseの「管理」などの権限があるかを確かめてください。番号が1つ違う1254301は、Baseで高度な権限が有効になっていない、または有効にできないときのエラーで、意味が異なります。スコープの正式名称と粒度は更新されることがあるので、実名はLark Developer Consoleの権限一覧で確認してください。

つまり「レコードを書けるならフィールドも書けるはず」という直感は、高度な権限が有効なBaseでは外れることがあります。筆者の環境では、レコードの書き込みは通り、フィールドの追加だけが1254302で弾かれました。なぜこの差が出たのかは、Baseの高度な権限の設定次第としか言えません。公式で確認できるのは、1254302は呼び出し元に高度な権限が無いときのエラーで、対処はデータ表またはBaseの「管理」などの権限を与えること、というところまでです。レコード操作でも同じコードが返り得るので、「レコードは書けるから権限は足りている」とは判断できません。

回避策は大きく3つあります。Baseでアプリに管理権限を与える（高度な権限が有効な場合。足りなければスコープも追加する）、手動UIとAPIを役割分担させる、用途ごとに別アプリを作る、の3つです。管理権限を自分で付けられず当日中に動かしたいなら、2番目が現実解になります。詳しい使い分けは後述します。

Lark Bitable APIのスコープ早見表

Bitable関連でよく見るスコープの違いを整理します。ここを最初に押さえておくと、Permission deniedの原因を絞り込みやすくなります。

表のとおり、フィールド操作を伴う作業には、bitable:app か、フィールド操作用のスコープ（base:field:create など）が要ります。Baseで高度な権限が有効なら、Base側でデータ表またはBaseの「管理」などの権限も要ることがあります。逆に言えば、データを入れたり更新したりするだけならレコード操作系のスコープで足りるので、最初に「自分のやりたいことはデータ操作なのか、構造変更なのか」を切り分けるのが先決です。

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

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

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

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

• レコードのbatch_updateで、関連付けの列に十数件ぶんの紐付けを書き込む：あっさり動く（レコードを書き込む権限で足りた）
• フィールドを複数本追加するAPI：全部 Permission denied

タスクの大半は自動化できているのに、最初の「列を作る」一手だけが手動UIに戻されたわけです。筆者のBaseで高度な権限が有効だったか、どう設定されていたかは確かめていません。公式の説明に当てはめると、Base側の高度な権限が足りなかったと考えられます。アプリに必要な権限が無いまま「全部APIで回します」と設計すると、こうして最後の一歩で立ち止まることがあります。

管理権限をすぐに付けられない環境なら、スキーマ変更を含む作業は、最初から手動UIが混じる前提で設計しておくと安全です。

回避策3パターン

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

パターン1：Baseの管理権限を与え、足りなければスコープを追加する（正攻法）

最初に確かめるのはBase側の権限です。公式の説明では、1254302は呼び出し元にBaseの高度な権限が無いときのエラーで、対処はデータ表またはBaseの「管理」などの権限を与えることです。アプリとして呼んでいるなら、アプリを文書アプリとしてBaseに追加し、「管理」権限を与えます。

1. Developer Consoleで、アプリにBitable系のAPIスコープを1つ以上有効にしておく（1つも無いと、手順4の検索にアプリが出てこない）
2. Baseの「…」メニューを開く
3. その他のメニュー（中国語版では「更多」）を開き、文書アプリの追加（同「添加文档应用」）を選ぶ
4. アプリを検索して追加し、権限を「管理」にする

メニュー名は表示言語で異なり、筆者は日本語UIでの表記を確認できていません。中国語版の公式ドキュメントでは「…」→「更多」→「添加文档应用」と案内されています。user_access_token でユーザーとして呼ぶ場合は、アプリの追加ではなく、そのユーザー本人がBaseで「管理」などの権限を持っている必要があります（高度な権限の設定で役割を付ける方法もあります）。

それでも通らないなら、アプリのスコープを疑います。Lark Developer Consoleで該当アプリを開き、bitable:app か base:field:create のどちらかを申請します。公式の権限の説明では、審査が必要な権限は、バージョンを作成して管理者の審査を通ると有効になります。審査が要らない権限は申請後すぐ有効になります。この2つのスコープがどちらに当たるかは筆者は確認できていないので、Developer Consoleの表示で確かめてください。筆者の環境では、承認が当日中に下りませんでした。同じ種類の作業がこの先も続くなら、早めに整えておくと後が楽です。単発なら次のパターン2に逃がすほうが速いことがあります。

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

権限の付与を待たずに進めるなら、操作を役割で分けます。

1. フィールドの追加・削除・型変更：ユーザーが手動UIで実施（数本なら短時間で終わる、というのが筆者の感覚です）
2. レコードのCRUD・データ紐付け：APIで自動化

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

パターン3：用途ごとに別アプリを新規作成する

データ入力用と構造管理用など、用途ごとにアプリを分けたいときの選択肢です。構造管理用のアプリにだけフィールド操作用のスコープ（bitable:app や base:field:create など）を持たせれば、責務を分けられます。Baseで高度な権限が有効なら、新しいアプリも文書アプリとして追加し、管理権限を与える必要があります。

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

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

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

パターン1や3でアプリのスコープを追加する場合、Lark Developer Consoleでの流れはおおむね次のとおりです。メニュー名は表示言語によって異なり、下の表記は目安です。

1. Developer Console で該当アプリを開く
2. 権限（スコープ）を設定する画面に移動する
3. bitable:app か base:field:create など、必要なスコープを検索して申請する
4. 審査が必要な権限なら、バージョン管理の画面で新バージョンを作成し、リリースを申請する
5. 管理者の審査が通ると有効になる（審査が要らない権限は、申請した時点で有効になる）

審査が要る場合は、承認する管理者が判断しやすいよう、用途を具体的に伝えておくと話が早くなります。「スキーマ変更を自動化するため、列の追加削除をAPIで実施する必要がある」のように、なぜそのスコープが要るのかを書いておくのがおすすめです。

承認後にも1つつまずきました。筆者の環境では、承認後しばらくは新しいスコープが反映されず、tenant_access_token を取り直した後に通りました。ただ、取り直したことが効いたのか、時間が経っただけなのかは特定できていません。公式の取得APIの説明では、有効期限が30分以上残っているうちに呼ぶと、同じトークンが返るとされています。

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

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

Lark Bitableで何かを内製・外注する前に、次を確認しておくと、設計の後半で権限に足を取られにくくなります。着手前の数分の確認で、後の手戻りを減らせます。

• Baseで高度な権限が有効か（有効なら、レコード操作でも構造変更でも「管理」などの権限が要る場合がある。1254302は呼び出し元に高度な権限が無いときに返る）
• やりたい操作はデータ操作か、構造変更か（レコードの読み書きだけならレコード操作系のスコープ。列やテーブルをいじるなら bitable:app か、フィールド操作用・テーブル操作用のスコープ）
• APIを呼ぶアプリやユーザーにBaseの管理権限を与えられるか（アプリを文書アプリとして追加できるのは誰か。追加の前に、アプリでBitable系のスコープを1つ以上有効にしておく）
• 構造変更を自動化したいか（自動化したいなら bitable:app か、base:field:create などフィールド操作用のスコープが要る。手動UIで済むなら追加は不要）
• スコープ追加の承認に誰のハンコが要るか（審査が必要な権限か、必要なら承認者は誰で何日かかるか）
• 当日納期のタスクがあるか（あるなら手動UIとAPIのハイブリッド前提で設計する）
• アプリを分けるべきか（データ入力用と構造管理用で責務が分かれるなら別アプリも検討）
• 使うトークンの種類を把握しているか（tenant_access_token でアプリとして呼ぶか、user_access_token でユーザーとして呼ぶかで、Base側で権限を与える相手が変わる）

このチェックリストの肝は最初の3項目です。高度な権限が有効か、「データを入れたいだけ」なのか「構造ごと自動で変えたい」のか、誰が権限を与えられるのかで、必要な権限もスコープも承認の有無も変わります。ここを曖昧にしたまま「Larkで全部自動化します」と進めると、後半で止まりやすくなります。

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

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

この表で見えるのは、「データ操作は自動化向き、構造変更は権限が揃わないと手動UIが混じる」という線引きです。計画段階でこの線を引いておけば、「列追加まで全部APIで」という実態に合わない見積もりを避けやすくなります。

外注するときの確認項目

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

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

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

アンチパターン3つ

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

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

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

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

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

アンチパターン3：スコープが反映されないとき、原因を切り分けずに決めつける

筆者の環境では、スコープの承認後しばらく反映されず、tenant_access_token を取り直した後に通りました。ただ、原因は特定できていません。公式の説明では、有効期限が30分以上残っているうちに取得APIを呼んでも、同じトークンが返ります。「トークンを取り直せば直る」と決めつけず、審査が通ったか、時間を置くと変わるか、呼び出しに使っているトークンはどれかを順に確かめてください。

よくある質問

Q. エラー1254302の原因は何ですか？

公式の説明では、1254302は呼び出し元にBaseの高度な権限が無いときのエラーです。多くの場合、Baseで高度な権限が有効になっていることが背景にあります。公式が案内する対処は、データ表またはBaseの「管理」などの権限を与えることです。アプリの場合は、先にBitable系のAPIスコープを1つ以上有効にしておきます。そのうえでBaseの「…」から、その他のメニュー、文書アプリの追加と進んでアプリを追加し、「管理」権限を与えます。user_access_token でユーザーとして呼ぶ場合は、そのユーザー本人がBaseで「管理」などの権限を持っている必要があります（高度な権限の設定で役割を付ける方法もあります）。

Q. フィールドを追加するのに bitable:app は必須ですか？

必須ではありません。公式のリファレンスでは、フィールド作成APIの必要スコープは bitable:app と base:field:create のどちらか1つを有効にすれば足りる、とされています。

Q. レコードは書けるのに、なぜフィールドだけ弾かれるのですか？

公式の説明では、1254302は呼び出し元にBaseの高度な権限が無いときのエラーです。多くの場合、Baseで高度な権限が有効になっていることが背景にあります。公式が案内する対処は、データ表またはBaseの「管理」などの権限を与えることです。同じコードはレコード作成・更新のエラー表にも載っていて、フィールド専用ではありません。筆者の環境では、この状態でもレコードの書き込みは通り、フィールドの作成だけが弾かれました。どこまで通るかは高度な権限の設定次第なので、1254302が出たら、呼び出し元にデータ表またはBaseの「管理」などの権限があるかを確認してください。

まとめ：Lark Bitable APIは権限とスコープを着手前に確かめる

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

1. 1254302は、呼び出し元にBaseの高度な権限が無いときのエラー。多くの場合はBaseで高度な権限が有効になっていることが背景にあり、データ表またはBaseの「管理」などの権限を与えるのが公式の対処。レコード操作でも返り得る
2. アプリのスコープは bitable:app か、フィールド操作用のスコープ（base:field:create など）のどちらか1つが要る。審査が必要な権限は、バージョンを作成して管理者の審査を通ると有効になる。審査が要らない権限は申請後すぐ有効になる
3. 手動UIとAPIのハイブリッド設計を、計画の最初から織り込む

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

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

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

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

業務システムを内製するか外注するか、どの業務から自動化するかは、ツールの制約を知ってから決めるほうが手戻りが少なくなります。どこから手を付けるか迷っている段階なら、まずは現在地を知るところからで十分です。

無料のAI活用診断を受ける（6問・約1分） →