인증

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(키의 처음 8개 16진수 문자로 flp_ 접두사 포함)만 반환됩니다.

{
  "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에 표시된 감사 로그에 기록됩니다.