17. 連携APIとAPIキー

連携APIを使うと、自分のプログラム、表計算ファイル、スクリプトからプロジェクトのデータを機械的に読み出せます。対象は、プロジェクト一覧、ケーブル・資材の明細、分電盤の回路表と端子台一覧、数量集計、図面パッケージの構成です。このAPIは読み取り専用で、図面やプロジェクトを変更することはありません。

APIキーを取得できるのは誰か

APIキーは、運営者がアカウントごとに許可します。アカウントに許可が与えられると、プロフィールページにAPIキーカードが表示されます。許可がなければカードは表示されません。1つのアカウントが同時に持てる有効なキーは最大5つです。

キーから見えるプロジェクトは、あなた自身が見えるものと同じです。自分のプロジェクトと、依頼に応じて共有されたプロジェクトです。共有プロジェクトの明細と集計は、共有設定でエクスポートが許可されている場合にのみ返されます。

キーの作成

プロフィールページのAPIキーカードで、新しいキーボタンをクリックします。
キーに名前を付けます（例：そのキーを使うプログラムの名前）。
権限範囲を選びます。プロジェクトの読み取りはプロジェクト一覧とプロジェクトのデータを、ドキュメントの読み取りは明細、集計、図面パッケージを返します。プログラムが本当に必要とするものだけを選んでください。
有効期限を選びます。30日、90日、365日のいずれかです。期限切れのキーは使えなくなるため、新しいキーを作成してください。
現在のパスワードを入力します（パスワードのないアカウントでは、直前のサインインが必要です）。最初のキーでは、API利用規約に同意してください。

作成後、キーが表示されるのは一度だけです。コピーして安全な場所に保管してください。後で一覧に表示されるのは先頭部分（avk_…）のみで、作成日と有効期限、最終使用日、呼び出し回数が併せて表示されます。新しいキーについては、メール通知も送信されます（キー自体は含まれません）。

キーの無効化

カードのキーの横にある無効化ボタンを押すと、そのキーは直ちに使えなくなります。この操作は元に戻せません。キーを使わなくなったとき、キーを使っていたプログラムを廃止するとき、またはキーが漏えいした疑いがあるときは、キーを無効化してください。

セキュリティのヒント

キーはパスワードと同じように扱ってください。キーを知っている人は、指定された権限範囲であなたのプロジェクトを読み取れます。
ソースコードではなく、シークレットの保管場所（パスワードマネージャー、サーバーの環境変数、CIのシークレット変数）に保管してください。gitリポジトリにコミットしないようにし、共有の表計算ファイルやメールにも載せないでください。
ブラウザ上で動くコードでは使わないでください（Webページ、ブラウザ拡張機能）。そこでは誰でもキーを読み取れます。キーを置く場所は、サーバー、スクリプト、デスクトップアプリです。
プログラムごとに専用のキーを作り、可能な限り狭い権限範囲と短い有効期限を設定してください。そうすれば、1つのキーを無効化しても他のものは止まりません。

プログラムからの利用

キーはリクエストヘッダーにBearerトークンとして送ります：Authorization: Bearer avk_…。エンドポイントは/api/v1/の下にあり（例：GET /api/v1/projects）、応答はJSONです。OpenAPI形式の詳細な仕様は/api/v1/openapi.jsonで入手でき、多くの開発ツールで取り込めます。

呼び出し回数は、キーごと、およびアカウントごとに制限されています（既定では1分あたり60回、1日あたり10,000回）。上限を超えるとサーバーは429を返すので、しばらく待ってください。Webサイトへのサインイン（クッキー）ではAPIは使えず、キーでWebインターフェースにサインインすることもできません。