Box APIの作成から権限設定までしてAPIでファイルを操作する

サービスアカウントや権限の理解に自分が苦しんだので、これらの設定方法の備忘。

目的

サーバーで動作するアプリから Box API を利用してファイルのダウンロード、アップロード、移動などを行う。

アプリの種類

カスタムアプリ - Box 開発者向けドキュメントポータル
サーバー上の処理から API を呼ぶならカスタムアプリを選んでおけばよい。

認証方法

認証方法の選択 - Box 開発者向けドキュメントポータル
カスタムアプリだと認証方式として以下の選択肢がある。

• OAuth2.0
• JWT(ID + Secret + Key Pair)
• クライアント資格情報（ID+Secret)
• 開発者トークン（1 時間限定、標準入力必須）

サーバーサイドの別アプリから API を叩く場合、JWT かクライアント資格情報になる。
開発者トークンは手元での API 検証程度。標準入力からトークンを与える必要がある、かつトークンが 1 時間限定なので実環境では使えない。

アプリの承認

承認 - Box 開発者向けドキュメントポータル
エンタープライズでの Box 利用だと、認証方法と有効になっている Enterprise 設定によっては管理者による明示的な承認が必要。

カスタムアプリを作成して承認されると自動的にサービスアカウントが生成され、アプリはこのアカウントとして各処理を実行する。
スコープ次第ではこのアカウントは強力な権限を持つため、アプリ作成時に承認が必要になる。

変更の再承認

アプリケーションのスコープまたはアクセスレベルが変更された場合は、アプリケーションを再承認する必要がある。

サービスアカウント

当初はこれが分かっておらず、どうやっても既存フォルダにアクセスできない…と困っていた。

サービスアカウント - Box 開発者向けドキュメントポータル

アプリを作成して承認されると、アプリに対応するサービスアカウントが生成される。これは独立した 1 ユーザとして振る舞う。このアカウントにも組織の設定に応じて専用のディスク容量が割り当てられる。
サービスアカウントの権限は開発者コンソールの設定に従う。上述の通り、権限変更の際は再承認が必要になる。

Box UI からサービスアカウントを使ってログインできるのはプライマリ管理者（組織の最上位の管理者）のみなので、一般的にはサービスアカウントをユーザとして UI 操作に使うことはできない。
また、サービスアカウントは管理コンソールの「ユーザーとグループ」に一覧表示されない。

サービスアカウントのフォルダとコラボレーション

サービスアカウントは 1 ユーザ相当であり、自身のフォルダツリーやコンテンツ所有権を持っている。Box にログインしたときの自分のユーザでのビューのような状態。デフォルトだと空。

既存のフォルダやファイルを API から操作するには、その対象のコラボレータにサービスアカウントを追加する必要がある。
サービスアカウントをコラボレータに追加する際は一般ユーザと同様にメールアドレスを使って招待する。
ただし、組織によっては Box に招待できるメールアドレスをドメインで制限しており、サービスアカウントのデフォルトのメールアドレスを招待できない場合がある。
この場合、自分の Box アカウントで手作りしたフォルダを API から利用するのではなく、API からフォルダを作成してコラボレータとして自分のユーザを招待するような操作をすることで解決できる。

※他の方法もあるかもしれないが、私の要件はこれで満たせたので調べておらず。

まとめ

個人的につまったポイントは、アプリにはサービスアカウントという固有ユーザが紐付いており、既存フォルダを API から操作するにはこのユーザをコラボレータに追加する必要がある、という点。
アプリを作った直後に適当な既存フォルダを API で取得しようとすると、権限が足りているはずでも 404 エラーになる。
コラボレータでない（参照権限がない）場合は 403 の権限系のエラーではなく 404 Not Found になるらしい。これも悩んだポイント。
これは上述の通りサービスアカウントをコラボレータ設定する必要があった、というのが原因だった。

Box は API 自体やドキュメントがかなり充実していてぱっと見た印象はいいが、CLI が node の 14 系までしか対応してなかったり(2022 年 10 月時点)、Web の UI 上だとサービスアカウントがわかりにくいなどモヤッとすることが多い…
この記事が誰かの助けになれば幸いです。