認証

API キー認証

すべての API リクエストには、Bearer トークンスキームを使用して Authorization ヘッダーに API キーを含める必要があります：

Authorization: Bearer flp_your_api_key_here

API キーの作成

FloopFloop ダッシュボードの Account → API Keys に移動して、API キーを作成・管理します。

• 各アカウントは最大 5 つのアクティブな API キーを持てます
• キーは作成時に一度だけ表示されます — 安全な場所に保管してください
• キーはダッシュボードからいつでも失効させることができます
• すべてのキーはプレフィックス flp_ で始まります

キーのセキュリティ

• API キーを共有したり、バージョン管理システムにコミットしたりしないでください
• アプリケーション内でキーを保存するには環境変数を使用してください
• 定期的にキーをローテーションし、未使用のキーを失効させてください
• 各キーには固有のレート制限バケットがあります

レート制限

API エンドポイントには API キーごとに以下のレート制限があります：

レート制限情報はレスポンスヘッダーに含まれています：X-RateLimit-Remaining および X-RateLimit-Reset。

認証の確認

GET /api/v1/user/me

このエンドポイントを使用して API キーが有効であることを確認します。認証済みユーザーのプロフィールを返し、すべての公式 SDK および CLI の floop whoamiコマンドで使用される標準的な “認証テスト” 呼び出しです。

curl https://floopfloop.com/api/v1/user/me \
  -H "Authorization: Bearer flp_your_api_key_here"

レスポンス (200):

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}

• role — 通常アカウントは "user"、プラットフォームスタッフは "admin"。
• source — リクエストの認証方法。プログラム認証情報は "api_key"、デバイス認可 CLI フローは "cli_token"。

ここで 401 UNAUTHORIZED が返された場合、キーが欠落しているか、失効しているか、または不正な形式です。403 FORBIDDEN はアカウントは存在するが、API アクセスに必要な Business プランがないことを意味します（API 概要の 要件 を参照）。

プログラムによる API キー管理

ほとんどのユーザーはダッシュボードからキーを作成しますが、同じ機能は CI ジョブからのキーローテーション、使用状況の監査のためのキー一覧表示、UI を介さずに漏洩したキーの失効などのオーケストレーションシナリオ向けに API でも利用可能です — これは CLI の floop keys list/create/remove が行うことを反映しています。

API キーの一覧表示

GET /api/v1/api-keys

アカウント上のすべてのアクティブ（失効していない）キーのメタデータを返します。平文のキー情報は返されません — keyPrefix（flp_ プレフィックス付きキーの最初の 8 文字の 16 進数）のみです。

{
  "data": {
    "keys": [
      {
        "id": "key_abc",
        "name": "ci-deploy",
        "keyPrefix": "flp_a1b2c3d4",
        "scopes": null,
        "lastUsedAt": "2026-04-24T18:30:00Z",
        "createdAt": "2026-04-01T12:00:00Z"
      }
    ]
  }
}

API キーの作成

POST /api/v1/api-keys

{
  "name": "ci-deploy"    // required, 1-100 chars
}

レスポンス (201):

{
  "data": {
    "id": "key_xyz",
    "rawKey": "flp_a1b2c3d4…full-40-hex…",
    "keyPrefix": "flp_a1b2c3d4"
  }
}

rawKey は一度だけ表示されます— 以降の読み取りでは keyPrefix のみが返されます。すぐに保管してください。各アカウントは最大 5 つのアクティブなキーに制限されており、上限に達するとリクエストは 409 LIMIT_EXCEEDEDを返します — まず未使用のキーを失効させてください。

キーの作成には Business プランが必要です。非 Business アカウントからのリクエストは、メッセージ “Creating API keys requires the Business plan” とともに 403 FORBIDDEN を返します。プラットフォーム管理者はこの制限を回避できます。

API キーの失効

DELETE /api/v1/api-keys/{keyId}

パスパラメータとしてキーの id（例：key_xyz）を渡します。キーは即座に無効化されます — ワーカーで既に処理中のリクエストは完了する可能性がありますが、新しいリクエストは認証されません。

レスポンス (200):

{ "data": { "success": true } }

• 自己失効はブロックされます。 リクエストを行っているのと同じキーで DELETE を呼び出すと 400 VALIDATION_ERRORが返されます — これにより CLI が呼び出し中に自分自身を切断することを防ぎます。別のキーを使用するか、ダッシュボードから失効させてください。
• 不明または既に失効したキーは 404 NOT_FOUND を返します。

公式 SDK の apiKeys.remove()ヘルパーは id またはキー名のどちらも受け入れ、リスト呼び出しを通じてクライアント側で名前 → id に解決します。API 自体は id のみを受け入れます。

失効したキーは復元できません。代替として新しいキーを作成してください。失効は Account → API Keys に表示される監査ログに記録されます。