APIキーとアクセストークン

APIキーは、プログラムがLinkHarbor APIにアクセスするための手段です。人ではなくワークスペースに属し、スコープで許可したことだけを実行できます。実際の呼び出しでは、キーを有効期間の短いアクセストークンに交換します。

#APIキーを作成できる人

• ワークスペースのオーナーと管理者。エディターとビューアーには、「コールバック＆API」で「連携済みアプリ」カードだけが表示されます
• Creator Pro以上。Creator Freeでは、カードに「APIキーはCreator Pro以上で利用できます。」と表示されます
• 同時に有効にできるのは、Creator Proで最大5個、Creator Agencyで最大20個、Enterpriseで最大50個です

上限に達すると、キーの作成は409 limit_reachedで失敗します。先に不要なキーを削除してください。

#APIキーを作成する

1. ナビゲーションの「コールバック＆API」を開きます
2. 「APIキー」カードで「+ 新しいキーを作成」をクリックします
3. 「名前（任意）」に、後でキーを見分けられる名前を入力します（例：「CI/CDパイプライン」「ショップ同期」）
4. 「スコープ」で、分野ごとに「読み取り」または「書き込み」を選びます
5. 「キーを作成」をクリックします
6. 「キーシークレット（非公開）」をすぐにコピーし、安全な場所に保管します
7. ダイアログを閉じます。キーIDは一覧でいつでも確認できます

「名前（任意）」

最大64文字です。名前がない場合、キーは一覧に「APIキー #ID」と表示されます。

「スコープ」

少なくとも1つ必要です。「書き込み」には同じ分野の「読み取り」が自動的に含まれます。統計と応援の支払いは読み取り専用、ワークスペーステンプレートは書き込み専用です。すべてのスコープはスコープの詳細で説明しています。

「キーシークレット（非公開）」

lt_で始まり、ちょうど一度だけ表示されます（「⚠️ 一度しか表示されません — 今すぐコピーしてください！」）。LinkHarborはそのハッシュしか保存しないため、後で再表示することはできません。

「キーID:」

数字と大文字のA〜Fからなる16文字です（例：6F668EA6598B0692）。秘密ではなく、コピーボタン付きで一覧に表示されます。

#キーの一覧

有効な各キーには、名前、「有効」のステータス、キーID、スコープ、「作成日」、「最終使用日:」または「まだ使用されていません」が表示されます。最終使用日時は、キーを使った呼び出しのたびに（最大1分に1回）更新されます。「↺ 更新」で一覧を再読み込みします。

#キーをアクセストークンに交換する

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

アクセストークンです。すべてのリクエストでAuthorization: Bearer <token>として送信します。

expires_in

有効期間（秒）：900、つまり15分です。リフレッシュトークンはありません。期限が切れたら、キーIDとシークレットで新しいトークンを取得してください。

トークンはワークスペースを表し、キーのスコープをそのまま持ちます。人のようなロールはありません。ダッシュボードでオーナーと管理者に限られているエンドポイント（メンバー、請求、ドメインの管理、Webhook、ワークスペース設定）は、APIキーのトークンでは常に拒否されます。例外は、対応するスコープで使える短縮リンクとワークスペーステンプレート、そしてread:workspacesでのコールバックシークレットの読み取り（平文のシークレットを除く）です。

#失敗とロック

api_key_lockedの場合、残り時間はdetails.retry_after_secにあります。交換に成功するとカウンターはリセットされます。

#キーの削除と入れ替え

1. キーの横にある「削除」をクリックします
2. 確認のためDELETEと入力します
3. 「完全に削除」をクリックします

キーはすぐに使えなくなります。すでに発行されたアクセストークンもその時点から使えなくなり、401 invalid_tokenが返されます。ローテーションのボタンはありません。キーを切り替えるには、新しいキーを作成し、プログラムをそちらに移してから古いキーを削除してください。

#プランが下がった場合

ワークスペースがCreator Freeに移行すると、すべてのAPIキーが取り消されます。キーの数が少ないプランに移行すると、最新のキーが残り、それ以外は取り消されます。取り消されたキーは後でアップグレードしても戻らないので、その時点で新しく作成してください。オーナーには、無効になった機能を記載したメールが届きます。詳しくは解約とダウングレードをご覧ください。

#安全な管理

• シークレットはシークレットマネージャーや環境変数にのみ保管し、ソースコードやGitリポジトリには絶対に入れないでください
• ブラウザで動くコードや、ユーザーのデバイス上のアプリでは絶対に使わないでください
• アプリケーションごとに、できるだけ少ないスコープで別々のキーを作成してください
• 不要になったキーはすぐに削除してください
• 漏えいの疑いがある場合は、キーを削除して新しく作成してください