APIキーの作成と管理

プロフィール → API（APIキー）を開き、API：APIキーを作成を選択して、名前と権限を指定してください。キーを生成を選択する前に制限と有効期限を確認し、結果のダイアログが開いている間にキーをコピーしてください。キー全体が表示されるのは一度だけです。

始める前に

• 連携に使用するアカウントにサインインしてください。APIキーはアカウントのプロフィールで管理します。1つのワークスペースに制限することもできます。
• ツールに必要なプロトコルと権限を確認してください。個別に識別して失効できるよう、ツールごとに別のキーを作成してください。
• キーを非公開で保管できる場所を用意してください。公開リポジトリ、共有するスクリーンショット、サポートへのメッセージに載せないでください。
• ワークスペースやフォルダーを制限する場合は、そのワークスペースに所属し、連携先のフォルダーを把握していることを確認してください。

手順：キーの生成と保存

1. APIキーを探す。 アバターのアカウントメニューを開き、プロフィールを選択して、プロフィールのナビゲーションで**API（APIキー）**を選択してください。APIキーを直接開くこともできます。
2. フォームを開く。 キー一覧の上にあるAPI：APIキーを作成を選択してください。
3. 用途を名前にする。 用途に、ツール名と用途など、後で見分けられるラベルを入力してください。ラベルはキーを識別するもので、認証情報ではありません。名前は64文字以内です。
4. 権限を選ぶ。 何ができますか？で読み取り専用、アップロードのみ、フルアクセスのいずれかを選択してください。読み取り専用では一覧表示とダウンロードができます。アップロードのみではアップロード処理とフォルダーの作成ができますが、既存ファイルの一覧表示、ダウンロード、削除はできません。新規作成だけに限定される保証はありません。アクセス権がある場合、同名のRESTアップロードによって既存ファイルにバージョンが追加されることがあります。フルアクセスは最も広い権限です。フォームでは最初にフルアクセスが選択されるため、必要な権限を明示的に選んでください。
5. 制限を確認する。 制限と有効期限を開き、以下のオプションで意図したプロトコル、ワークスペース、アドレス、スケジュール、使用量に制限してください。新しい制限なしのフォームではアカウント全体、すべてのプロトコル、有効期限なしも初期設定されています。
6. 概要を確認する。 フォーム下部の説明をツールの用途と照らし、アクセス範囲、権限、有効期限が意図どおりか確認してください。
7. 認証情報を生成する。 キーを生成を選択してください。作成に成功すると、**「キー名」の準備ができました。**という見出しのダイアログにキー全体が表示されます。
8. 閉じる前に保存する。 表示されたキーの横のコピーを使って非公開で保管し、ツールの認証情報の設定に入力してください。保存後にのみ完了を選択してください。ダイアログを閉じると、キー全体を再表示できません。

ツールに合った制限を選ぶ

展開したフォームでは、質問ごとにオプションがまとめられています。

• アクセス範囲はどこまでですか？ プロトコルですべてのプロトコルまたは選択したもののみを選択してください。後者を選ぶ場合は、REST API、WebDAV、SFTP、「S3」ゲートウェイのうち少なくとも1つをチェックしてください。どのプロトコルもチェックしない場合、フォームは制限を省略し、キーはすべてのプロトコルで使用できます。生成前に実際に必要なプロトコルを選択してください。ワークスペースを選んでアカウント全体を1つのワークスペースに変更できます。ワークスペースを選択した後、フォルダーを選択…で範囲をフォルダーとその配下に制限できます。選択画面ではフォルダーを選択で確定します。
• どこから利用できますか？ 許可するIP範囲にカンマ区切りのアドレスまたはCIDR範囲を追加するか、毎週指定した曜日と時間帯のみをオンにしてタイムゾーン、曜日、開始と終了の時刻を選択してください。
• どれくらい利用できますか？ 必要に応じて毎分のリクエスト数、ダウンロード量／日（GB）、最大ファイルサイズ（MB）、同時転送数を入力してください。空欄の場合、キー固有の使用量制限は追加されません。プランやその他の適用されるサービスの制限は引き続き適用されます。
• いつまで利用できますか？ 有効期限なし、30日後に有効期限切れ、90日後に有効期限切れから選択してください。

保存前に2つのプロトコル上の制約を確認してください。フォルダーに制限したキーはWebDAVまたはS3ゲートウェイでのみ使用できます。IP許可リストを追加すると、そのキーではSFTPを使用できなくなります。これらを組み合わせる場合はフォームの説明を確認してください。

結果の確認

新しいキーがAPI（APIキー）の一覧に表示されます。行には権限、プロトコル、アクセス範囲、最終使用と、該当する場合は有効期限が表示されます。一覧には認証情報全体ではなく識別子の一部が表示されます。

選択したプロトコルを使うようツールを設定し、目的の操作を試してください。キーの作成に成功しても、権限、アクセス範囲、アクセス条件が合わなければ、その操作は拒否されます。

キーの確認、交換、失効

名前またはプレフィックスで検索と権限フィルターでキーを探してください。行の末尾の展開ボタンを選択すると、設定、アクセス制限、操作を確認できます。

キーは作成後に編集できません。重複した設定を作成を選択すると、既存の設定の一部が入力された新規キーフォームが開きます。交換用キーの設定をよく確認してください。有効期限は有効期限なしから始まり、使用量制限は空欄です。生成前に意図した有効期限と制限を再設定してください。交換用キーを生成して保存し、ツールを更新してから、適切な時点で古い認証情報を失効してください。

キーを失効するには、その行を展開して招待を取り消す（この画面ではAPIキーを失効する操作です）を選択し、確認ダイアログを確認してから再度招待を取り消すを選択してください。この操作は元に戻せません。そのキーを引き続き使用するツールは拒否されます。複数の行のチェックボックスを選ぶと、選択数に応じた一括失効操作が使えます。選択数に応じて、たとえば2を無効化と表示されます。

S3認証情報

APIトークンとS3の認証情報の組は別の設定です。キーが**「S3」ゲートウェイを許可している場合、行を展開し、S3認証情報の横の有効化を選択してください。表示されるダイアログにはS3互換クライアント用のアクセスキーID**、シークレットアクセスキー、エンドポイント、リージョンが表示されます。

完了を選択する前にシークレットを保存してください。後から有効・表示で他のS3の詳細を再表示できますが、シークレットは取得できません。期限切れのキーではS3アクセスを有効にできません。S3を除外したキーには許可されていませんが表示されます。

アカウントの上限と応答メッセージ

無料プランではアカウント全体でユーザーごとにAPIキーを3件まで使用できます。他のプランでも合計20件が上限です。期限切れのキーも失効するまで数に含まれます。ワークスペースの制限はアクセス範囲を変えますが、キーの数え方は変えません。無料プランでもキーを生成できます。ワークスペースを指定するには、そのメンバーである必要があります。

作成時の応答	対処方法
Name is required	用途に空でないラベルを入力してください。
Name must be 64 characters or less	ラベルを短くしてください。ラベルを変えてもトークンの安全性は変わりません。
Maximum of 20 API keys reached	別のキーを生成する前に、未使用の認証情報を失効してください。
The free plan allows 3 API keys. Delete one or upgrade for more.	期限切れを含め、キー一覧全体を確認してください。
Not a member of that workspace	所属するワークスペースを選択してください。キーの作成によってメンバーにはなりません。
Folder not found in that workspace	選択したワークスペースでフォルダー選択画面を開き直し、有効なフォルダーを選択してください。
Invalid IP/CIDR entry: "…"	意図したアクセスの境界を削除せず、指定されたアドレスまたはサブネットを修正してください。

20件の上限は無料プランの上限より先に確認されます。生成に成功したキーでも使用時に拒否されることがあります。リクエストの使用量が計上される前に、プロトコル、アドレスと時間の条件、指定フォルダー、操作のスコープ、ワークスペースの固定が確認されます。フルアクセスでもロールによる制限は別途適用されます。

連携に影響する単位と有効期限

ダウンロード量／日（GB）と最大ファイルサイズ（MB）は1024を基準とする単位を使用します。1 GBは1,073,741,824バイト、1 MBは1,048,576バイトです。リクエストと同時転送は回数です。保存する使用量制限には正の整数が必要です。0を指定しても無制限にはなりません。キー固有の制限を設けない場合は任意の欄を空にしてください。適用されるプランとワークスペースの制約は引き続き有効です。

30日後に有効期限切れと90日後に有効期限切れは初回使用時ではなく作成時から計算されます。有効期限なしでは有効期限が設定されません。認証情報は作成に成功すると使用可能になるため、ジョブを有効にする前に保存して設定してください。表示された有効期限を停止時刻と考え、認証キャッシュによるアクセス延長に依存しないでください。

RESTでは、キーに明示された制限と適用されるプランの上限のうち、より厳しい方がリクエスト回数、同時転送数、ダウンロードバイト数に適用されます。WebDAV、S3、SFTPではリクエスト回数と同時転送数にプランの上限は適用されませんが、認証情報に明示された制限は適用されます。ダウンロードバイト数の上限はすべてのプロトコルに関係します。署名付きダウンロードURLを要求すると、URLが実際に取得されなくても、発行時にファイル容量が計上されます。日ごとのダウンロードカウンターはUTCの日付が変わる時刻にリセットされます。週間の利用可能時間には選択したタイムゾーンが使われます。

トークンの使用と確認

RESTクライアントでは、Authorization: Bearerに続けてdos_トークン全体を送信してください。読み取り専用認証情報ではこの安全なリクエストを実行できますが、アップロードのみ認証情報ではワークスペースを一覧表示できません。

# DOSYA_API_KEY must already be supplied privately by your secret store.
curl --fail-with-body --silent --show-error \
  'https://api.dosya.dev/api/workspaces' \
  -H "Authorization: Bearer $DOSYA_API_KEY"

HTTP 200とworkspaces配列が目的のアカウントに対応することを確認してください。ワークスペースを固定すると、この配列は選択したワークスペースに絞られます。アップロード用の認証情報の場合は、代わりに小さなファイルをアップロードし、返されたファイルIDで確認してください。セッションの状態確認は許可されますが、通常のファイル一覧表示はできません。

Invalid or expired API keyを伴う401は、トークンが無効、期限切れ、または失効済みであることを示します。api surfaceを示す403はREST APIが除外されていることを示します。認証情報のスコープ、リクエストメソッド、パスを示すメッセージは、その操作に別の権限が必要であることを意味します。ワークスペースのアクセス範囲を広げても解決しません。429ではRetry-Afterが秒単位で返されます。認証中の一時的な503は5秒後の再試行を求めるもので、キーの紛失を意味しません。

APIキー自体の管理にはサインイン済みのアカウントセッションが必要です。Bearerトークンではプロフィールのエンドポイントを通じて他のキーを作成、一覧表示、失効できません。提示されたキーにフルアクセスがあっても、他の認証情報は保護されます。

制限とトラブルシューティング

APIキー全体とS3シークレットは後から取得できません。いずれかを紛失した場合は交換用の認証情報を作成し、必要に応じて古いキーを失効してください。一覧の識別子の一部をコピーしてもツールの認証には使えません。

キーを生成ができない場合は名前とメッセージを確認してください。アカウントのキー上限に達した場合は、不要なキーを削除するかプランを確認してから別のキーを作成してください。期限切れのキーも一覧に表示されるため、合計を確認する際に含めてください。

ツールが拒否される場合は、権限、プロトコル、アクセス範囲、有効期限、IP許可リスト、利用可能時間を確認してください。フォルダーに制限されたキーはREST APIやSFTPでは動作しません。IPで制限されたキーではSFTPクライアントを使用できません。実際の要件を確認する前にアクセスを広げて解決しようとしないでください。

認証情報の問題が解決しない場合は非公開のサポートに連絡してください。キーのラベル、選択したプロトコル、メッセージを共有し、キー全体、認証ヘッダー、S3シークレット、生成された認証情報のコマンドは含めないでください。

よくある質問

Doneを選択した後にキー全体を再表示できますか？

できません。トークン全体は作成時に一度だけ表示されます。保存しなかった場合は交換用を作成して連携を更新し、未使用の古いキーを失効してください。

Duplicate settingsですべての制限が保持されますか？

いいえ。交換用フォームを確認してください。使用量制限は空欄で、有効期限は有効期限なしから始まります。交換用を生成する前にこれらを明示的に設定してください。

セッションを失効するとAPIキーも失効しますか？

APIキーは別に管理されます。連携による認証を停止するには、このページでキーを失効してください。サインイン中のブラウザとアプリはプロフィール → セッションで確認できます。

関連ガイド

• アクティブなセッションを確認する
• APIキーの既存のチュートリアルを見る
• WebDAVの既存のチュートリアルを見る