認証

FreeMaint は 2 種類の認証方式に対応しています。JWT（/auth/login で発行され、当社の Web アプリとモバイルアプリが使用）と、API キー（/company-settings/api で作成し、お客様独自の連携で使用）です。

JWT (ユーザーセッション)

1. POST /認証/ログイン — 本文: {メールアドレス、パスワード}。 {access_token、refresh_token} を返します。
2. Authorization ヘッダーを送信する — すべてのリクエストに Authorization: Bearer <access_token> を付けます。
3. 有効期限が切れたら更新する — 新しい access_token を取得するには、refresh_token を付けて /auth/refresh に POST します。アクセストークンの有効期限は 2 時間です。

API キー (サーバー統合)

1. /company-settings/api または /profile/api-keys を開きます — 管理者は Business プラン以上で、「会社の設定 > API」からキーを作成します。ロールに「個人用APIキーを作成」権限があるユーザーは、「プロフィール > セキュリティ > APIキー」で自分用のキーを作成します。 「連携を管理」権限を持つロール（例：「連携管理者」テンプレート）は、管理者でなくても会社のキーを作成・失効・削除できます。キーを別の人に引き渡せるのは管理者だけです。
2. 「新しいキー」をクリックします — 必要に応じて有効期限とアクセスレベル（既定は読み取り専用）を設定します。生のキーは 1 回だけ表示されます。すぐにコピーしてください。
3. 使ってください — すべてのリクエストで Authorization: Bearer fmk_<rawKey> を送信します。形式：fmk_ で始まり、その後に 16 進数 32 文字が続きます。

セキュリティに関する注意事項

• API キーは SHA-256 ハッシュとして保存されるため、キーを表示するダイアログを閉じると、元の値は復元できなくなります
• キーを取り消すと、そのキーはすぐに無効になります。行は監査のために保持されます
• 各キーは 1 つの会社に属し、その会社のデータにしかアクセスできません。他社のレコードは単に「見つからない」扱いになります
• 有効期間が短い統合のために、キーにオプションのexpiresAtを設定できます
• アクセスレベルは、所有者の権限にさらにかける上限です：READ（既定、クエリのみ）、READ_STOCK（クエリ + adjustStock、出庫専用キオスクに最適）、FULL（所有者のロールが許可するすべての操作）
• 各キーは所有者として動作します。すべての呼び出しに所有者の権限とデータの可視範囲が適用され、キーが書き込んだ内容には所有者の名前が記録されます。所有者が無効化されると、管理者が「会社の設定 > API」で別のユーザーに引き継ぐまで、キーは拒否されます（401、コード API_KEY_OWNER_INACTIVE）。キーの値は変わりません。

連携のテスト

専用のサンドボックス環境はありません。API キーは常に、それが属する会社の実データにアクセスします。安全にテストする方法は二つあります。（1）二つ目の会社をテスト用の会社として使う——会社間の分離は全顧客を隔てているのと同じ仕組みなので、そこで行ったことが本番データに届くことはありません。API キーには Business プランが必要なため、その会社も Business プランである必要があります。無料の会社ではキーを作成できません。（2）読み取りのみの作業には、アクセスレベル READ のキーを作成してください。すべてのクエリを実行でき、ミューテーションは一切実行できないため、何も変更できません。書き込みに進む段階では、READ_STOCK キーが adjustStock だけを許可します。