> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# APIキー

> スクリプト、CI ジョブ、AI コーディングクライアントが、付与した権限だけで Alforse API を呼び出せるようにする、会社単位のシークレットを作成します。

APIキーを使うと、ユーザーがサインインしなくても、プログラムから Alforse を呼び出せます。管理者や開発者は、ブラウザでのサインインを完了できないスクリプト、CI パイプライン、AI コーディングクライアント向けにキーを作成します。すべてのキーは**設定 → APIキー**で管理します。

## キーの仕組み

キーは 1 つの会社に紐づき、独自の権限スコープのリストを持ちます。Alforse は各リクエストを 2 つの制限に対して同時に認可し、両方が許可した場合にのみリクエストが成功します。

* キーに保存されているスコープ
* その時点で、キーの作成者が持つ権限

そのため、キーが作成者の権限を超えることはありません。作成者から権限を削除すれば、キーもその権限を失います。ほかの会社のデータには常にアクセスできません。

### キーが必要な場合と不要な場合

| クライアント | 接続方法 |
| - | - |
| Claude.ai、Claude Desktop、ChatGPT | **OAuth**。接続は認可したユーザーのロールと会社を引き継ぐため、キーは不要です。 |
| Claude Code、Cursor、VS Code、Codex | APIキー |
| ヘッドレススクリプトと CI | APIキー |
| stdio のみ対応のクライアント | APIキー（`mcp-remote` 経由で接続） |

両方のフローの詳細は、認証をご覧ください。

## キーを作成する

Alforse screenshot**設定 → APIキー：マスクされたプレビュー、スコープ、レート制限を表示するキー一覧と、1 回限りの「このキーは一度しか表示されません」ダイアログ**

完全なキーは、作成時に一度だけ表示されます。

1. **設定 → APIキー**に移動し、**新しいAPIキー**を選択します。
2. **名前**を入力します。会社内で一意である必要があります。
3. 必要に応じて**有効期限**を設定します。空欄のままにすると、有効期限のないキーになります。
4. 連携に必要なスコープを付与して保存します。
5. ダイアログから、すぐにキーをコピーします。同じダイアログに MCP の接続コマンドも表示されます。

このダイアログが、完全なキーが表示される唯一の場所です。その後、Alforse は平文の値を破棄し、SHA-256 ハッシュと、一覧用の 5 文字のプレビューだけを保持します。元の値は復元できないため、キーを紛失した場合は削除して再作成する必要があります。

HEADS UP

**キーはパスワードと同様に扱ってください**

キーはベアラーシークレットです。持っている人は誰でも、そのスコープの範囲で操作できます。シークレットマネージャーに保管し、ソース管理にコミットしないでください。漏洩した場合は、キーを削除して代わりのキーを作成することでローテーションします。

## API を呼び出す

すべての操作は、`https://api.alforse.com` の `/api/v1/{module}/{operation}` への `POST` で、キーを `Authorization` ヘッダーにベアラートークンとして指定します。

```http theme={null}
POST /api/v1/{module}/{operation}
Host: api.alforse.com
Authorization: Bearer alf_your_key_here
Content-Type: application/json
```

必要なのはこれだけです。キーには開くべきセッションも、更新すべきトークンもありません。リクエストが届くと、Alforse は提示されたキーをハッシュ化し、そのハッシュを持つ保存済みレコードを探し、キーが期限切れでないこと、レート制限に達していないことを確認します。その後にのみ、操作が実行されます。

NOTE

**受け付けるヘッダー**

`Authorization: Bearer alf_…` を使用してください。互換性のため、Alforse は `alforse-key` ヘッダーからもキーを読み取ります。API v1 は、`alf_` キー以外の資格情報をすべて拒否します。OAuth コネクターが接続するのは MCP エンドポイントであり、API v1 ではありません。

## 権限、プラン、レート制限

### スコープ

各スコープは、`sales_view` や `inventory_create` のように `module_action` の形式で表されます。連携が使うものだけを付与してください。スコープのないキーは認証には通りますが、データの読み取りも書き込みもできません。スコープの編集とキーの削除は、すぐ次のリクエストから反映されます。

### プラン

キーが使えるのは、**Business** または **Partner** プランの会社だけです（機能 `API_KEYS`）。Starter プランでは、キーのスコープに関係なく、すべてのリクエストに `403` が返されます。

### レート制限

| 設定 | 値 |
| - | - |
| 新しいキーのデフォルト | **1 分あたり 60 リクエスト**（ウィンドウ `1m`） |
| プラットフォームポリシーで設定できるその他のウィンドウ | `1h`、`1d` |
| カウント単位 | キーごと |
| 確認できる場所 | キー一覧の**レート制限**列 |

アプリには上限の設定項目がありません。連携で本当にもっと必要な場合は、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 で直接公開します。キーがそこで参照できる範囲は、アプリの行レベルセキュリティポリシーによって制限されます。

HEADS UP

**Data API の書き込みはサービス層をスキップします**

直接書き込みを行っても、合計、ステータス、元帳記帳などの派生値は再計算されません。Alforse API に対応する操作がなく、変更が影響するすべてのレコードを把握している場合にのみ、Data API で書き込んでください。

## APIキーと Webhook

この 2 つの機能は逆方向の通信を担っており、どちらも他方には依存しません。

| | 方向 | 使用するシークレット |
| - | - | - |
| **APIキー** | 自社システムが Alforse を呼び出す | キー自体 |
| **[Webhook](https://docs.alforse.com/ja/docs/building/webhooks.md)** | 購読しているレコードが変更されると、Alforse が自社システムを呼び出す | Webhook 固有の署名シークレット（APIキーではありません） |

ほとんどの連携ではこの 2 つを組み合わせます。Webhook が変更を知らせ、連携はキーを使って最新のレコードを読み取ります。

## 関連項目

**Webhooks**

レコードが変更されたときに通知を受け取り、キーを使って読み取ります。

[Open](https://docs.alforse.com/ja/docs/building/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.