キーの仕組み
キーは 1 つの会社に紐づき、独自の権限スコープのリストを持ちます。Alforse は各リクエストを 2 つの制限に対して同時に認可し、両方が許可した場合にのみリクエストが成功します。- キーに保存されているスコープ
- その時点で、キーの作成者が持つ権限
キーが必要な場合と不要な場合
両方のフローの詳細は、認証をご覧ください。
キーを作成する
- 設定 → APIキーに移動し、新しいAPIキーを選択します。
- 名前を入力します。会社内で一意である必要があります。
- 必要に応じて有効期限を設定します。空欄のままにすると、有効期限のないキーになります。
- 連携に必要なスコープを付与して保存します。
- ダイアログから、すぐにキーをコピーします。同じダイアログに MCP の接続コマンドも表示されます。
API を呼び出す
すべての操作は、https://api.alforse.com の /api/v1/{module}/{operation} への POST で、キーを Authorization ヘッダーにベアラートークンとして指定します。
権限、プラン、レート制限
スコープ
各スコープは、sales_view や inventory_create のように module_action の形式で表されます。連携が使うものだけを付与してください。スコープのないキーは認証には通りますが、データの読み取りも書き込みもできません。スコープの編集とキーの削除は、すぐ次のリクエストから反映されます。
プラン
キーが使えるのは、Business または Partner プランの会社だけです（機能API_KEYS）。Starter プランでは、キーのスコープに関係なく、すべてのリクエストに 403 が返されます。
レート制限
アプリには上限の設定項目がありません。連携で本当にもっと必要な場合は、Alforse サポートにお問い合わせください。キーが上限を超えると、リクエストには
Retry-After と X-RateLimit-* ヘッダーとともに 429（Rate limit exceeded）が返されます。Retry-After の間隔だけ待ってから、リクエストを再送してください。
API を選ぶ
キーを使うと、2 つのインターフェースのどちらでも利用できます。まず Alforse API から始め、Alforse API にない操作に限って Data API を使ってください。Alforse API（推奨）
Alforse API の呼び出しは、サービス層を通ります。この層が、入力を検証し、権限を適用し、変更が影響する派生データを更新します。- 同じ操作、2 つのトランスポート。 操作は、HTTP（
POST /api/v1/{module}/{operation}）と MCP のどちらでも、同一の引数を受け付けます。 - リスクラベル。 すべての操作に
READ、WRITE、DESTRUCTIVEのタグが付いているため、クライアントはリスクの高い操作の前に確認を求められます。 - リファレンスと SDK。 API リファレンスには、サンプルと、クライアント SDK を生成するための OpenAPI 仕様が含まれます。
Data API
Data API は、テーブルとビューを REST で直接公開します。キーがそこで参照できる範囲は、アプリの行レベルセキュリティポリシーによって制限されます。APIキーと Webhook
この 2 つの機能は逆方向の通信を担っており、どちらも他方には依存しません。
ほとんどの連携ではこの 2 つを組み合わせます。Webhook が変更を知らせ、連携はキーを使って最新のレコードを読み取ります。