Styleflowで使用できるスコープの一覧と詳細について説明します。
📋 スコープとは
スコープは、APIにてアクセスできるStyleflowのリソースや機能を制限するためのアクセス制御情報です。
💡 スコープの特徴
- アクセス制御：特定のAPIエンドポイントへのアクセス権限を管理
- 最小権限の原則：必要最小限の権限のみを付与
- 複数指定可能：スペース区切りで複数のスコープを同時指定
- 階層構造：allスコープは個別スコープの上位権限を含む
🚨 重要なポイント
- 認可コード取得時またはアクセストークン取得時（password方式）にスコープを指定
- 指定したスコープに応じてAPIアクセス権限が決定される
- 不適切なスコープ指定はエラーの原因となる
📋 スコープ一覧表
| スコープ | 説明 |
|---|---|
| 📄 書類関連スコープ | |
applyDocument.read | 申請書類一覧取得、申請書類PDF取得、添付ファイル取得 |
applyDocument.create | 申請、保存、再申請、再保存、取り消し、承認、承認者再設定、却下、否決 |
applyDocument.delete | 申請書類削除 |
jurisdictionDocument.read | 所管書類一覧取得、所管書類PDF取得、添付ファイル取得 |
inspectionDocument.read | 保管書類一覧取得、保管書類PDF取得、添付ファイル取得 |
documents.read | 書類一覧取得 |
| 📝 フォーム・ルート関連スコープ | |
form.read | フォーム項目取得、フォームレイアウト取得 |
route.read | ルート一覧取得、ルート詳細取得、ルート判別、承認者取得 |
| 👤 社員情報関連スコープ | |
employee.all | 社員情報の取得、作成、更新、削除 |
employee.read | 社員情報の取得 |
employee.create | 社員情報の作成 |
employee.update | 社員情報の更新 |
employee.delete | 社員情報の削除 |
| 🏢 部門情報関連スコープ | |
department.all | 部門情報の取得、作成、更新、削除 |
department.read | 部門情報の取得 |
department.create | 部門情報の作成 |
department.update | 部門情報の更新 |
department.delete | 部門情報の削除 |
| 🎖️ 役職情報関連スコープ | |
position.all | 役職情報の取得、作成、更新、削除 |
position.read | 役職情報の取得 |
position.create | 役職情報の作成 |
position.update | 役職情報の更新 |
position.delete | 役職情報の削除 |
| 🎭 役割情報関連スコープ | |
part.all | 役割情報の取得、作成、更新、削除 |
part.read | 役割情報の取得 |
part.create | 役割情報の作成 |
part.update | 役割情報の更新 |
part.delete | 役割情報の削除 |
| 📋 割当・所属情報関連スコープ | |
assignment.all | 割当情報の取得、作成、削除 |
assignment.read | 割当情報の取得 |
assignment.create | 割当情報の作成 |
assignment.delete | 割当情報の削除 |
belongDepartment.all | 所属情報の取得、作成、更新、削除 |
belongDepartment.read | 所属情報の取得 |
belongDepartment.create | 所属情報の作成 |
belongDepartment.update | 所属情報の更新 |
belongDepartment.delete | 所属情報の削除 |
| 🔄 人事異動関連スコープ | |
personnelChange.all | 人事異動情報の取得、作成、更新、削除 |
personnelChange.read | 人事異動情報の取得 |
personnelChange.create | 人事異動情報の作成 |
personnelChange.update | 人事異動情報の更新 |
personnelChange.delete | 人事異動情報の削除 |
| 📊 マスタデータ関連スコープ | |
masterCode.all | 任意マスタの取得、作成、更新、削除 |
masterCode.read | 任意マスタの取得 |
masterCode.create | 任意マスタの作成 |
masterCode.update | 任意マスタの更新 |
masterCode.delete | 任意マスタの削除 |
masterData.all | 任意マスタデータの取得、作成、更新、削除 |
masterData.read | 任意マスタデータの取得 |
masterData.create | 任意マスタデータの作成 |
masterData.update | 任意マスタデータの更新 |
masterData.delete | 任意マスタデータの削除 |
💡 スコープ選択のポイント
- .all：対象リソースの全操作が可能
- .read：データの参照のみ可能
- .create/.update/.delete：特定の操作のみ可能
- 必要最小限のスコープを指定することでセキュリティを向上できます
💼 スコープ指定例
単一スコープ指定
scope=applyDocument.read
複数スコープ指定
scope=applyDocument.read employee.read department.read
全権限スコープ指定
scope=employee.all department.all
✅ スコープ設定のベストプラクティス
| 🎯 | 最小権限の原則：必要最小限のスコープのみを指定 |
| 📊 | 機能別制限：読み取り専用が必要な場合は.readスコープを使用 |
| 🔄 | 運用に応じた調整：アプリケーションの要件に応じてスコープを適切に選択 |
| ⚠️ | 権限管理：.allスコープは慎重に使用し、必要な場合のみ指定 |
| 📝 | ドキュメント化：使用するスコープとその理由を明確に記録 |
🚨 スコープ関連エラー
❌ よくあるエラー
| エラーシナリオ | 原因 | 対処法 |
|---|---|---|
| invalid_request | 存在しないスコープを指定 | 正確なスコープ名を確認し修正 |
| insufficient_scope | API実行に必要なスコープが不足 | 必要なスコープを追加して再認証 |
| access_denied | 許可されていないスコープを要求 | 適切な権限レベルのスコープに変更 |
🎯 まとめ
適切なスコープ設定により、StyleflowのOAuth認証でセキュアかつ効率的なAPI利用が実現できます。
🔑 スコープ設定の重要ポイント
- 最小権限：必要最小限のスコープで安全性を確保
- 機能分離：読み取り専用と変更権限の適切な使い分け
- 階層理解：.allスコープと個別スコープの関係性の把握
- 継続管理：アプリケーション要件の変化に応じたスコープ見直し
スコープを適切に設定して、StyleflowのAPIを安全かつ効果的に活用しましょう。